#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const os = require('os');
const readline = require('readline');
const crypto = require('crypto');
const {
  isManagedHookBasename,
  isManagedHookCommand,
  projectLocalHookPrefix,
  projectLegacySettingsHookCommand,
  projectManagedHookCommand,
  projectPathActionProjection,
  projectPortableHookBaseDir,
  projectPersistentPathExportActions,
  projectShellCommandText,
  projectCodexHookTomlCommand,
  shellHookOmitsBashRunner,
  buildLocalShellHookCommand,
} = require('../gsd-core/bin/lib/shell-command-projection.cjs');

// Bidirectional GSD slash-command namespace transformer (#3583).
// Required at module scope so the command list can be computed once per install
// and passed down to convertClaudeCommandToClaudeSkill, avoiding repeated
// fs.readdirSync + RegExp work for every skill.
const {
  transformContentToHyphen,
  readCmdNames: readGsdCommandNames,
} = require(path.join(__dirname, '..', 'scripts', 'fix-slash-commands.cjs'));
const {
  resolveAntigravityGlobalDir,
  getGlobalConfigDir,
  getGlobalSkillsBase,
} = require('../gsd-core/bin/lib/runtime-homes.cjs');
const {
  applyWorktreeBaseRef,
  readBaseRefFromSettings,
} = require('../gsd-core/bin/lib/worktree-base-ref.cjs');
const { resolveRuntimeConfigIntent } = require('../gsd-core/bin/lib/runtime-config-adapter-registry.cjs');

/**
 * Runtimes that register hyphen-form `name:` per #2808 AND copy agent bodies
 * verbatim (only branding swaps, no namespace conversion), so retired
 * `/gsd:<cmd>` colon refs leak into installed agent prose. Sibling fixes
 * #3583 / #3629 covered SKILL.md bodies, #3584 / #3606 covered runtime
 * emissions — this is the agent-body surface (#3677).
 *
 * Explicit allow-list rather than deny-list so unknown / future runtimes
 * default to "no rewrite" (better to leak than to mangle a runtime whose
 * namespace behavior we haven't verified).
 */
const HYPHEN_NAME_AGENT_RUNTIMES = new Set(['claude', 'qwen', 'hermes']);

/**
 * #3677 predicate — true when an agent body needs `/gsd:<cmd>` → `/gsd-<cmd>`
 * normalization at install time.
 */
function shouldNormalizeHyphenNamespaceInAgentBody(runtime) {
  if (typeof runtime !== 'string' || runtime === '') return false;
  return HYPHEN_NAME_AGENT_RUNTIMES.has(runtime);
}

/**
 * #3677 helper — applies the hyphen-namespace transform iff the predicate
 * says so. Pure function; safe to call unconditionally from the install
 * loop. Returns the input unchanged for runtimes that self-convert or
 * intentionally keep colon refs.
 */
function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
  if (!shouldNormalizeHyphenNamespaceInAgentBody(runtime)) return content;
  return transformContentToHyphen(content, cmdNames);
}

// Colors
const cyan = '\x1b[36m';
const green = '\x1b[32m';
const yellow = '\x1b[33m';
const red = '\x1b[31m';
const bold = '\x1b[1m';
const dim = '\x1b[2m';
const reset = '\x1b[0m';

// Codex config.toml constants
const GSD_CODEX_MARKER = '# GSD Agent Configuration \u2014 managed by gsd-core installer';
const GSD_CODEX_HOOKS_OWNERSHIP_PREFIX = '# GSD codex_hooks ownership: ';
// Codex's hook-enabling feature flag (issue #3566). Codex itself marks
// `codex_hooks` as a `legacy_key` in codex-rs/features/src/legacy.rs; the
// canonical current key under [features] is `hooks`. The installer always
// emits the canonical key going forward, recognizes legacy aliases as
// equivalent during reinstall, and migrates them forward on rewrite. The
// audit-marker string above is intentionally unchanged so existing
// installs' ownership lines continue to round-trip.
const CODEX_HOOKS_FEATURE_KEY = 'hooks';
const CODEX_HOOKS_FEATURE_LEGACY_KEYS = ['codex_hooks'];
const CODEX_HOOKS_FEATURE_ALL_KEYS = [CODEX_HOOKS_FEATURE_KEY, ...CODEX_HOOKS_FEATURE_LEGACY_KEYS];
function isCodexHooksFeatureKey(key) {
  return CODEX_HOOKS_FEATURE_ALL_KEYS.includes(key);
}

// #768 \u2014 Claude Code permissions.allow / permissions.deny entries.
// Pre-populated during Claude installs to eliminate first-run approval friction
// for gsd-core's own known-safe tool calls, and to add defense-in-depth deny
// entries for common credential files.
//
// Format: each string uses Claude Code's documented permission rule syntax \u2014
//   "Tool(pattern)"  e.g. "Bash(npx gsd-core *)", "Read(.planning/*)"
//   "Tool"           (bare tool name, no pattern)
//
// Merge policy: additive, non-destructive \u2014 existing user entries are preserved;
// GSD entries are appended only when not already present (idempotent).
const GSD_CLAUDE_ALLOW_PERMISSIONS = Object.freeze([
  'Bash(npx gsd-core *)',
  'Read(.planning/*)',
  'Write(.planning/*)',
  'Read(STATE.md)',
  'Write(STATE.md)',
]);
const GSD_CLAUDE_DENY_PERMISSIONS = Object.freeze([
  'Read(.env)',
  'Read(.env.*)',
  'Read(.secrets)',
]);

/**
 * Merge GSD-owned permission entries into a Claude Code settings object.
 *
 * Additive and idempotent: existing allow/deny entries are preserved; GSD
 * entries are appended only if not already present. No other permission sub-keys
 * (ask, disableBypassPermissionsMode, etc.) are touched.
 *
 * Defensive: if settings is not a plain object, returns immediately without
 * throwing. If permissions.allow / permissions.deny exist but are not arrays
 * (malformed settings), they are replaced with valid arrays.
 *
 * @param {object} settings - The parsed settings.json object to mutate in-place.
 */
function mergeClaudePermissions(settings) {
  if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) return;

  if (!settings.permissions || typeof settings.permissions !== 'object' || Array.isArray(settings.permissions)) {
    settings.permissions = {};
  }

  if (!Array.isArray(settings.permissions.allow)) {
    settings.permissions.allow = [];
  }
  if (!Array.isArray(settings.permissions.deny)) {
    settings.permissions.deny = [];
  }

  for (const entry of GSD_CLAUDE_ALLOW_PERMISSIONS) {
    if (!settings.permissions.allow.includes(entry)) {
      settings.permissions.allow.push(entry);
    }
  }
  for (const entry of GSD_CLAUDE_DENY_PERMISSIONS) {
    if (!settings.permissions.deny.includes(entry)) {
      settings.permissions.deny.push(entry);
    }
  }
}

// Copilot instructions marker constants
const GSD_COPILOT_INSTRUCTIONS_MARKER = '<!-- GSD Configuration \u2014 managed by gsd-core installer -->';
const GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER = '<!-- /GSD Configuration -->';

// #786 \u2014 GitHub Copilot CLI lifecycle hook constants.
// Copilot reads hook configs from <config>/hooks/*.json (repo scope: .github/hooks/,
// user scope: ~/.copilot/hooks/) with the shape { version, hooks: { <event>: [...] } }.
// Events use camelCase (sessionStart, preToolUse, postToolUse, ...). A `command`
// hook runs an INLINE shell command (bash / powershell), so the GSD hook is fully
// self-contained \u2014 there is no separate hook script to install, and therefore
// nothing that can dangle if a script copy is skipped. See
// https://docs.github.com/en/copilot/reference/hooks-configuration
const GSD_COPILOT_HOOK_FILE = 'gsd-session.json';
// Copilot parses a command hook's stdout as the hook-output JSON. For sessionStart
// the schema is `{ additionalContext?: string }` (the text is prepended to the
// session as context). So the hook must emit that JSON envelope — not bare text.
// The two messages contain no JSON-special characters, so they embed verbatim.
const GSD_COPILOT_SESSION_MSG_PRESENT =
  'GSD: .planning/STATE.md present - review the current phase and any blockers before acting.';
const GSD_COPILOT_SESSION_MSG_ABSENT =
  'GSD: no .planning/ workflow found - run /gsd-new-project to start a tracked workflow.';
const GSD_COPILOT_SESSION_HOOK_BASH =
  'if [ -f .planning/STATE.md ]; then ' +
  `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_PRESENT}"}'; else ` +
  `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_ABSENT}"}'; fi`;
const GSD_COPILOT_SESSION_HOOK_PWSH =
  'if (Test-Path .planning/STATE.md) ' +
  `{ '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_PRESENT}"}' } ` +
  `else { '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_ABSENT}"}' }`;

// #777 — Cursor CLI lifecycle hook constants.
// Cursor reads hook configs from <project-root>/.cursor/hooks.json (local) or
// ~/.cursor/hooks.json (global) with the shape { version: 1, hooks: { <event>: [...] } }.
// Events use camelCase: sessionStart, postToolUse, preToolUse, etc.
// A `command` hook entry runs an external script. GSD registers two managed hooks:
//   sessionStart → gsd-cursor-session-start.js  (context injection)
//   postToolUse  → gsd-cursor-post-tool.js       (STATE.md update monitor)
// Cursor docs: https://cursor.com/docs/hooks
const GSD_CURSOR_SESSION_HOOK_SCRIPT = 'gsd-cursor-session-start.js';
const GSD_CURSOR_POST_TOOL_HOOK_SCRIPT = 'gsd-cursor-post-tool.js';
// Marker comment embedded in managed hook entries so GSD can find+remove them.
const GSD_CURSOR_HOOK_MARKER = 'gsd-managed';

// GSD-managed files under hooks/lib/ (helpers required by gsd-*.sh hooks).
// git-cmd.js does not start with "gsd-" (shared classifier for #3129), gsd-graphify-rebuild.sh does.
const GSD_HOOK_LIB_FILES = ['git-cmd.js', 'gsd-graphify-rebuild.sh'];

const CODEX_AGENT_SANDBOX = {
  'gsd-executor': 'workspace-write',
  'gsd-planner': 'workspace-write',
  'gsd-phase-researcher': 'workspace-write',
  'gsd-project-researcher': 'workspace-write',
  'gsd-research-synthesizer': 'workspace-write',
  'gsd-verifier': 'workspace-write',
  'gsd-codebase-mapper': 'workspace-write',
  'gsd-roadmapper': 'workspace-write',
  'gsd-debugger': 'workspace-write',
  'gsd-plan-checker': 'read-only',
  'gsd-integration-checker': 'read-only',
};

// Copilot tool name mapping — Claude Code tools to GitHub Copilot tools
// Tool mapping applies ONLY to agents, NOT to skills (per CONTEXT.md decision)
const claudeToCopilotTools = {
  Read: 'read',
  Write: 'edit',
  Edit: 'edit',
  Bash: 'execute',
  Grep: 'search',
  Glob: 'search',
  Task: 'agent',
  WebSearch: 'web',
  WebFetch: 'web',
  TodoWrite: 'todo',
  AskUserQuestion: 'ask_user',
  SlashCommand: 'skill',
};

// Get version from package.json
const pkg = require('../package.json');

// #2517 — runtime-aware tier resolution shared with core.cjs.
// Hoisted to top with absolute __dirname-based paths so `gsd install codex` works
// when invoked via npm global install (cwd is the user's project, not the gsd repo
// root). Inline `require('../gsd-core/...')` from inside install functions
// works only because Node resolves it relative to the install.js file regardless
// of cwd, but keeping the require at the top makes the dependency explicit and
// surfaces resolution failures at process start instead of at first install call.
const _gsdLibDir = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib');
const { MODEL_PROFILES: GSD_MODEL_PROFILES } = require(path.join(_gsdLibDir, 'model-profiles.cjs'));
const {
  RUNTIME_PROFILE_MAP: GSD_RUNTIME_PROFILE_MAP,
  resolveTierEntry: gsdResolveTierEntry,
  EFFORT_SET: GSD_EFFORT_SET,
} = require(path.join(_gsdLibDir, 'core.cjs'));

// #443 — model-catalog and config-defaults.manifest.json exports needed only
// by effort-resolution code paths (resolveInstallTimeEffort /
// generateCodexAgentToml / Claude .md effort injection).  Loaded lazily the
// first time they are needed so that requiring install.js in test contexts that
// never trigger an install does NOT produce module-load-time side effects (the
// manifest read + hard throw) that could alter subprocess exit codes or stderr.
let _gsdEffortCatalogCache = null;
function _getGsdEffortCatalog() {
  if (_gsdEffortCatalogCache) return _gsdEffortCatalogCache;

  const { AGENT_DEFAULT_TIERS, renderEffortForRuntime } = require(path.join(_gsdLibDir, 'model-catalog.cjs'));

  const manifestPath = path.join(
    __dirname,
    '..',
    'gsd-core',
    'bin',
    'shared',
    'config-defaults.manifest.json'
  );
  let manifestData;
  try {
    manifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
  } catch (_err) {
    // Fail loudly — a missing manifest is a broken install, not a soft degradation.
    throw new Error(
      `gsd install: cannot load config-defaults.manifest.json at ${manifestPath}: ${_err.message}`
    );
  }

  const tierDefaults =
    (manifestData.effort &&
      manifestData.effort.routing_tier_defaults &&
      typeof manifestData.effort.routing_tier_defaults === 'object' &&
      !Array.isArray(manifestData.effort.routing_tier_defaults))
      ? manifestData.effort.routing_tier_defaults
      : { light: 'low', standard: 'high', heavy: 'xhigh' }; // guard: unreachable if manifest is valid

  const effortDefault =
    (manifestData.effort && typeof manifestData.effort.default === 'string')
      ? manifestData.effort.default
      : 'high'; // guard: unreachable if manifest is valid

  _gsdEffortCatalogCache = {
    AGENT_DEFAULT_TIERS,
    renderEffortForRuntime,
    EFFORT_MANIFEST_TIER_DEFAULTS: tierDefaults,
    EFFORT_MANIFEST_DEFAULT: effortDefault,
  };
  return _gsdEffortCatalogCache;
}

const {
  MINIMAL_SKILL_ALLOWLIST,
  PROFILES,
  isMinimalMode,
  stageSkillsForMode,
  readActiveProfile,
  writeActiveProfile,
  resolveEffectiveProfile,
  mostRestrictiveProfile,
  resolveProfile,
  loadSkillsManifest,
  stageSkillsForProfile,
  stageAgentsForProfile,
  stageSkillsForRuntimeAsSkills,
} = require(path.join(_gsdLibDir, 'install-profiles.cjs'));
// ADR-857 phase 4c: load capability registry (optional; missing → falls back to undefined)
let _capabilityRegistry;
try {
  _capabilityRegistry = require(path.join(_gsdLibDir, 'capability-registry.cjs'));
} catch (_) {
  _capabilityRegistry = undefined;
}
const {
  applyInstallerMigrationPlan,
  discoverInstallerMigrations,
  runInstallerMigrations,
} = require(path.join(_gsdLibDir, 'installer-migrations.cjs'));
const {
  assertInstallerMigrationsUnblocked,
  resolveInstallerMigrationPromptsForNonTty,
  summarizeInstallerMigrationResult,
} = require(path.join(_gsdLibDir, 'installer-migration-report.cjs'));
const {
  resolveRuntimeArtifactLayout,
} = require(path.join(_gsdLibDir, 'runtime-artifact-layout.cjs'));
const {
  planLegacyCleanup,
  applyLegacyCleanup,
} = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'legacy-cleanup.cjs'));
const {
  updateCacheFileName,
} = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'package-identity.cjs'));

// Parse args
const args = process.argv.slice(2);
const hasGlobal = args.includes('--global') || args.includes('-g');
const hasLocal = args.includes('--local') || args.includes('-l');
const hasUninstall = args.includes('--uninstall') || args.includes('-u');
const hasSkillsRoot = args.includes('--skills-root');
const hasPortableHooks = args.includes('--portable-hooks') || process.env.GSD_PORTABLE_HOOKS === '1';
const hasMinimal = args.includes('--minimal') || args.includes('--core-only');
const hasDryRun = args.includes('--dry-run');
// --profile=<name> or --profile=<n1>,<n2> (composable); mutually exclusive with --minimal
const _profileArgRaw = (() => {
  for (const arg of args) {
    if (arg.startsWith('--profile=')) return arg.slice('--profile='.length);
  }
  return null;
})();
// Resolve active profile name:
// 1. --minimal / --core-only → 'core' (back-compat alias)
// 2. --profile=<name> → named profile
// 3. neither → 'full' (default, back-compat)
// Note: when re-running as `gsd update` the marker is read later (after
// configDir is resolved) and may override 'full' — see writeActiveProfile call below.
const _profileIsCore = _profileArgRaw === 'core';
const _requestedProfileName = (hasMinimal || _profileIsCore) ? 'core' : (_profileArgRaw || null);

if (hasMinimal && _profileArgRaw) {
  console.error(`  ${yellow}Cannot specify both --minimal/--core-only and --profile${reset}`);
  process.exit(1);
}

function selectRuntimesFromArgs(runtimeArgs) {
  if (runtimeArgs.includes('--all')) {
    return ['claude', 'kimi', 'kilo', 'opencode', 'gemini', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline'];
  }
  if (runtimeArgs.includes('--both')) {
    return ['claude', 'opencode'];
  }

  const selected = [];
  if (runtimeArgs.includes('--claude')) selected.push('claude');
  if (runtimeArgs.includes('--opencode')) selected.push('opencode');
  if (runtimeArgs.includes('--gemini')) selected.push('gemini');
  if (runtimeArgs.includes('--kilo')) selected.push('kilo');
  if (runtimeArgs.includes('--codex')) selected.push('codex');
  if (runtimeArgs.includes('--copilot')) selected.push('copilot');
  if (runtimeArgs.includes('--antigravity')) selected.push('antigravity');
  if (runtimeArgs.includes('--cursor')) selected.push('cursor');
  if (runtimeArgs.includes('--windsurf')) selected.push('windsurf');
  if (runtimeArgs.includes('--augment')) selected.push('augment');
  if (runtimeArgs.includes('--trae')) selected.push('trae');
  if (runtimeArgs.includes('--qwen')) selected.push('qwen');
  if (runtimeArgs.includes('--hermes')) selected.push('hermes');
  if (runtimeArgs.includes('--kimi')) selected.push('kimi');
  if (runtimeArgs.includes('--codebuddy')) selected.push('codebuddy');
  if (runtimeArgs.includes('--cline')) selected.push('cline');
  return selected;
}

// Runtime selection - can be set by flags or interactive prompt
let selectedRuntimes = selectRuntimesFromArgs(args);

// WSL + Windows Node.js detection
// When Windows-native Node runs on WSL, os.homedir() and path.join() produce
// backslash paths that don't resolve correctly on the Linux filesystem.
if (process.platform === 'win32') {
  let isWSL = false;
  try {
    if (process.env.WSL_DISTRO_NAME) {
      isWSL = true;
    } else if (fs.existsSync('/proc/version')) {
      const procVersion = fs.readFileSync('/proc/version', 'utf8').toLowerCase();
      if (procVersion.includes('microsoft') || procVersion.includes('wsl')) {
        isWSL = true;
      }
    }
  } catch {
    // Ignore read errors — not WSL
  }

  if (isWSL) {
    console.error(`
${yellow}⚠ Detected WSL with Windows-native Node.js.${reset}

This causes path resolution issues that prevent correct installation.
Please install a Linux-native Node.js inside WSL:

  curl -fsSL https://fnm.vercel.app/install | bash
  fnm install --lts

Then re-run: npx ${pkg.name}@latest
`);
    process.exit(1);
  }
}

// Helper to get directory name for a runtime (used for local/project installs)
function getDirName(runtime) {
  if (runtime === 'copilot') return '.github';
  if (runtime === 'opencode') return '.opencode';
  if (runtime === 'gemini') return '.gemini';
  if (runtime === 'kilo') return '.kilo';
  if (runtime === 'codex') return '.codex';
  if (runtime === 'antigravity') return '.agent';
  if (runtime === 'cursor') return '.cursor';
  if (runtime === 'windsurf') return '.windsurf';
  if (runtime === 'augment') return '.augment';
  if (runtime === 'trae') return '.trae';
  if (runtime === 'qwen') return '.qwen';
  if (runtime === 'hermes') return '.hermes';
  if (runtime === 'kimi') return '.kimi-code';
  if (runtime === 'codebuddy') return '.codebuddy';
  if (runtime === 'cline') return '.cline';
  return '.claude';
}

/**
 * Get the config directory path relative to home directory for a runtime
 * Used for templating hooks that use path.join(homeDir, '<configDir>', ...)
 * @param {string} runtime - 'claude', 'opencode', 'gemini', 'codex', or 'copilot'
 * @param {boolean} isGlobal - Whether this is a global install
 */
function getConfigDirFromHome(runtime, isGlobal) {
  if (!isGlobal) {
    // Local installs use the same dir name pattern
    return `'${getDirName(runtime)}'`;
  }
  // Global installs - OpenCode uses XDG path structure
  if (runtime === 'copilot') return "'.copilot'";
  if (runtime === 'opencode') {
    // OpenCode: ~/.config/opencode -> '.config', 'opencode'
    // Return as comma-separated for path.join() replacement
    return "'.config', 'opencode'";
  }
  if (runtime === 'gemini') return "'.gemini'";
  if (runtime === 'kilo') return "'.config', 'kilo'";
  if (runtime === 'codex') return "'.codex'";
  if (runtime === 'antigravity') {
    if (!isGlobal) return "'.agent'";
    const antigravityDir = resolveAntigravityGlobalDir();
    const rel = path.relative(os.homedir(), antigravityDir);
    const segments = rel.split(path.sep).filter(Boolean);
    if (segments.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel)) {
      return segments.map((seg) => `'${seg}'`).join(', ');
    }
    // If resolution points outside HOME (e.g. via env override), keep the
    // stable legacy template so generated path.join() calls remain valid.
    return "'.gemini', 'antigravity'";
  }
  if (runtime === 'cursor') return "'.cursor'";
  if (runtime === 'windsurf') return "'.windsurf'";
  if (runtime === 'augment') return "'.augment'";
  if (runtime === 'trae') return "'.trae'";
  if (runtime === 'qwen') return "'.qwen'";
  if (runtime === 'hermes') return "'.hermes'";
  if (runtime === 'codebuddy') return "'.codebuddy'";
  if (runtime === 'cline') return "'.cline'";
  if (runtime === 'kimi') return "'.config', 'agents'";
  return "'.claude'";
}

/**
 * Compatibility seam for tests and older installer consumers.
 * Runtime home resolution now lives in runtime-homes.cjs.
 */
function getGlobalDir(runtime, explicitDir = null) {
  return getGlobalConfigDir(runtime, explicitDir);
}
const banner = '\n' +
  cyan + '   ██████╗ ███████╗██████╗\n' +
  '  ██╔════╝ ██╔════╝██╔══██╗\n' +
  '  ██║  ███╗███████╗██║  ██║\n' +
  '  ██║   ██║╚════██║██║  ██║\n' +
  '  ╚██████╔╝███████║██████╔╝\n' +
  '   ╚═════╝ ╚══════╝╚═════╝' + reset + '\n' +
  '\n' +
  '  GSD Core ' + dim + 'v' + pkg.version + reset + '\n' +
  '  Git. Ship. Done.\n' +
  '  A meta-prompting, context engineering and spec-driven\n' +
  '  development workflows for Claude Code, OpenCode, Gemini, Kimi CLI, Kilo, Codex, Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, Cline and CodeBuddy.\n';

// Pure seam: parse --config-dir / -c from an arbitrary args array.
// Returns the path string, '' for an empty equals-form value, or null when the
// flag is absent.  Space-separated form returns null (not an error string) when
// the next token is missing or flag-looking — callers that want process.exit
// behaviour must check after calling this function.
// Exported via module.exports so unit tests can exercise it directly.
function parseConfigDirFromArgs(argsArray) {
  const configDirIndex = argsArray.findIndex(arg => arg === '--config-dir' || arg === '-c');
  if (configDirIndex !== -1) {
    const nextArg = argsArray[configDirIndex + 1];
    // No value / next token is a flag → signal "missing" by returning null
    if (!nextArg || nextArg.startsWith('-')) {
      return null;
    }
    return nextArg;
  }
  // Handle --config-dir=value and -c=value format.
  // Use indexOf('=') + 1 so that = signs inside the path value are preserved.
  const configDirArg = argsArray.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
  if (configDirArg) {
    return configDirArg.slice(configDirArg.indexOf('=') + 1);
  }
  return null;
}

// Parse --config-dir argument
function parseConfigDirArg() {
  const result = parseConfigDirFromArgs(args);
  if (result === null) {
    // Check if the space-separated form was present but missing a value
    const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
    if (configDirIndex !== -1) {
      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
      process.exit(1);
    }
    return null;
  }
  if (result === '') {
    console.error(`  ${yellow}--config-dir requires a non-empty path${reset}`);
    process.exit(1);
  }
  return result;
}
const explicitConfigDir = parseConfigDirArg();
const hasHelp = args.includes('--help') || args.includes('-h');
const forceStatusline = args.includes('--force-statusline');

if (!hasSkillsRoot) console.log(banner);

if (hasUninstall) {
  console.log('  Mode: Uninstall\n');
}

// Show help if requested
if (hasHelp) {
  console.log(`  ${yellow}Usage:${reset} npx ${pkg.name} [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-g, --global${reset}              Install globally (to config directory)\n    ${cyan}-l, --local${reset}               Install locally (to current directory)\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--kilo${reset}                    Install for Kilo only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--kimi${reset}                    Install for Kimi CLI only\n    ${cyan}--copilot${reset}                 Install for Copilot only\n    ${cyan}--antigravity${reset}             Install for Antigravity only\n    ${cyan}--cursor${reset}                  Install for Cursor only\n    ${cyan}--windsurf${reset}                Install for Windsurf only\n    ${cyan}--augment${reset}                 Install for Augment only\n    ${cyan}--trae${reset}                    Install for Trae only\n    ${cyan}--qwen${reset}                    Install for Qwen Code only\n    ${cyan}--hermes${reset}                  Install for Hermes Agent only\n    ${cyan}--cline${reset}                   Install for Cline only\n    ${cyan}--codebuddy${reset}              Install for CodeBuddy only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall GSD (remove all GSD files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n    ${cyan}--portable-hooks${reset}          Emit \$HOME-relative hook paths in settings.json\n                              (for WSL/Docker bind-mount setups; also GSD_PORTABLE_HOOKS=1)\n    ${cyan}--profile=<name>${reset}         Install a named skill profile. Profiles:\n                              core     — ${PROFILES.core.length} main-loop skills incl. phase (~130 desc tokens)\n                              standard — ${PROFILES.standard.length} skills incl. phase, review, config (~700)\n                              full     — all skills (default)\n                              Composable: --profile=core,audit installs union of closures.\n                              Profile is persisted and respected by \`gsd update\`.\n    ${cyan}--minimal${reset}                 Alias for --profile=core (back-compat).\n                              Cuts cold-start overhead from ~12k tokens to ~700.\n                              Alias: --core-only.\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime and location)${reset}\n    npx ${pkg.name}\n\n    ${dim}# Install for Claude Code globally${reset}\n    npx ${pkg.name} --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx ${pkg.name} --gemini --global\n\n    ${dim}# Install for Kilo globally${reset}\n    npx ${pkg.name} --kilo --global\n\n    ${dim}# Install for Codex globally${reset}\n    npx ${pkg.name} --codex --global\n\n    ${dim}# Install for Kimi CLI globally${reset}\n    npx ${pkg.name} --kimi --global\n\n    ${dim}# Install for Kimi CLI under ~/.kimi-code${reset}\n    npx ${pkg.name} --kimi --global --config-dir ~/.kimi-code\n\n    ${dim}# Install for Copilot globally${reset}\n    npx ${pkg.name} --copilot --global\n\n    ${dim}# Install for Copilot locally${reset}\n    npx ${pkg.name} --copilot --local\n\n    ${dim}# Install for Antigravity globally${reset}\n    npx ${pkg.name} --antigravity --global\n\n    ${dim}# Install for Antigravity locally${reset}\n    npx ${pkg.name} --antigravity --local\n\n    ${dim}# Install for Cursor globally${reset}\n    npx ${pkg.name} --cursor --global\n\n    ${dim}# Install for Cursor locally${reset}\n    npx ${pkg.name} --cursor --local\n\n    ${dim}# Install for Windsurf globally${reset}\n    npx ${pkg.name} --windsurf --global\n\n    ${dim}# Install for Windsurf locally${reset}\n    npx ${pkg.name} --windsurf --local\n\n    ${dim}# Install for Augment globally${reset}\n    npx ${pkg.name} --augment --global\n\n    ${dim}# Install for Augment locally${reset}\n    npx ${pkg.name} --augment --local\n\n    ${dim}# Install for Trae globally${reset}\n    npx ${pkg.name} --trae --global\n\n    ${dim}# Install for Trae locally${reset}\n    npx ${pkg.name} --trae --local\n\n    ${dim}# Install for Hermes Agent globally${reset}\n    npx ${pkg.name} --hermes --global\n\n    ${dim}# Install for Hermes Agent locally${reset}\n    npx ${pkg.name} --hermes --local\n\n    ${dim}# Install for Cline globally${reset}\n    npx ${pkg.name} --cline --global\n\n    ${dim}# Install for Cline locally${reset}\n    npx ${pkg.name} --cline --local\n\n    ${dim}# Install for CodeBuddy globally${reset}\n    npx ${pkg.name} --codebuddy --global\n\n    ${dim}# Install for CodeBuddy locally${reset}\n    npx ${pkg.name} --codebuddy --local\n\n    ${dim}# Install for all runtimes globally${reset}\n    npx ${pkg.name} --all --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx ${pkg.name} --kilo --global --config-dir ~/.kilo-work\n\n    ${dim}# Install to current project only${reset}\n    npx ${pkg.name} --claude --local\n\n    ${dim}# Uninstall GSD from Cursor globally${reset}\n    npx ${pkg.name} --cursor --global --uninstall\n\n  ${yellow}Notes:${reset}\n    The --config-dir option is useful when you have multiple configurations.\n    It takes priority over CLAUDE_CONFIG_DIR / OPENCODE_CONFIG_DIR / GEMINI_CONFIG_DIR / KILO_CONFIG_DIR / CODEX_HOME / KIMI_CONFIG_DIR / COPILOT_CONFIG_DIR / COPILOT_HOME / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR / AUGMENT_CONFIG_DIR / TRAE_CONFIG_DIR / QWEN_CONFIG_DIR / HERMES_HOME / CLINE_CONFIG_DIR / CODEBUDDY_CONFIG_DIR environment variables.\n    Kimi CLI defaults to the first existing generic skills root: ${cyan}~/.config/agents/skills${reset}, then ${cyan}~/.agents/skills${reset}; if neither exists, GSD creates ${cyan}~/.config/agents${reset}.\n    Use ${cyan}--config-dir ~/.kimi-code${reset} or ${cyan}KIMI_CONFIG_DIR=~/.kimi-code${reset} for brand-specific Kimi installs.\n`);
  process.exit(0);
}

/**
 * Compute the path prefix used for `@file` references in installed command/skill
 * markdown. For global installs into a runtime config dir under $HOME, we
 * normally substitute the home prefix with `$HOME` so paths expand correctly
 * inside double-quoted shell commands. OpenCode is exempt on every platform:
 * its `@file` include syntax does NOT shell-expand `$HOME`, so a literal
 * `@$HOME/...` is treated as a path relative to the config command/ dir, which
 * resolves to `command/$HOME/...` (file not found). For OpenCode we always emit
 * the absolute resolved path. (#2376 Windows, #2831 macOS/Linux.)
 *
 * @param {object} args
 * @param {boolean} args.isGlobal - Global runtime install vs local project
 * @param {boolean} args.isOpencode - Whether the runtime is OpenCode
 * @param {boolean} args.isWindowsHost - process.platform === 'win32'
 * @param {string} args.resolvedTarget - Absolute target dir, forward-slashed
 * @param {string} args.homeDir - User home dir, forward-slashed
 * @returns {string} pathPrefix ending with '/'
 */
function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget, homeDir }) {
  if (isGlobal && resolvedTarget.startsWith(homeDir) && !isOpencode) {
    return '$HOME' + resolvedTarget.slice(homeDir.length) + '/';
  }
  return `${resolvedTarget}/`;
}

/**
 * Normalize a raw `process.execPath` to a stable, upgrade-safe node binary
 * path. On Homebrew installs, `process.execPath` resolves symlinks and returns
 * the versioned Cellar path (e.g.
 * `/usr/local/Cellar/node/25.8.1/bin/node`). Baking that path into hook
 * commands causes `dyld: Library not loaded` errors after `brew upgrade node`
 * because the shared libraries referenced by the Cellar binary have changed
 * SOVERSION. (#3181)
 *
 * The stable Homebrew symlinks (`/usr/local/bin/node` for Intel,
 * `/opt/homebrew/bin/node` for Apple Silicon) survive upgrades — Homebrew
 * re-points them atomically. We prefer those when a Cellar path is detected.
 *
 * Non-Homebrew installs (NVM, system node, Windows, etc.) are returned as-is.
 */
function normalizeNodePath(execPath) {
  if (!execPath) return execPath;
  // Intel Homebrew: /usr/local/Cellar/node/<version>/bin/node
  // or /usr/local/Cellar/node@20/<version>/bin/node
  if (/^\/usr\/local\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
    return '/usr/local/bin/node';
  }
  // Apple Silicon Homebrew: /opt/homebrew/Cellar/node/<version>/bin/node
  // or /opt/homebrew/Cellar/node@18/<version>/bin/node
  if (/^\/opt\/homebrew\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
    return '/opt/homebrew/bin/node';
  }
  return execPath;
}

/**
 * Resolve the absolute path to the node binary running the installer.
 * Used as the runner for .js hooks so they execute in GUI/minimal-PATH
 * runtimes (Gemini, Antigravity, Codex CLIs launched from a Finder
 * shortcut etc.) where bare `node` is not on `/usr/bin:/bin:/usr/sbin:/sbin`
 * and the hook would fail with `node: command not found` (#2979).
 *
 * Returns a forward-slash-normalized, double-quoted path so the emitted
 * command is shell-safe across POSIX and Windows. `process.execPath`
 * gives the absolute path of the node binary actively running the
 * installer — that is the version the user just installed under, and
 * the right default runtime for hooks invoked under the same install.
 *
 * When `process.execPath` is a versioned Homebrew Cellar path, the stable
 * Homebrew symlink is returned instead to survive `brew upgrade node` (#3181).
 */
function resolveNodeRunner() {
  const execPath = typeof process.execPath === 'string' ? process.execPath : '';
  if (!execPath) return null;
  const stablePath = normalizeNodePath(execPath);
  // JSON.stringify produces a properly escaped double-quoted shell token,
  // safe for paths containing spaces or unusual characters.
  return JSON.stringify(stablePath.replace(/\\/g, '/'));
}

/**
 * Rewrite legacy `node .../gsd-*.js` command strings in settings.hooks to use
 * the absolute Node binary path (#2979 follow-up: CR feedback on #3002).
 *
 * The original #2979 fix only emitted absolute paths for *newly registered*
 * hooks. Pre-existing entries kept their bare `node ` prefix on reinstall,
 * which left them broken under minimal-PATH GUI runtimes — exactly the
 * failure mode the original fix was meant to close. This walker normalizes
 * any managed-hook entry whose command starts with bare `node ` to
 * `<absoluteRunner> <script>` while leaving non-managed and non-bare-node
 * entries (user-authored hooks, shell scripts, etc.) untouched.
 *
 * Returns true if any entry was rewritten.
 */
function resolveBashRunner(opts) {
  const platform = (opts && opts.platform) || process.platform;
  if (platform !== 'win32') return 'bash';

  const env = (opts && opts.env) || process.env;
  const exists = (opts && opts.existsSync) || fs.existsSync;
  const candidates = [];
  if (env.GSD_BASH_PATH) candidates.push(env.GSD_BASH_PATH);
  if (env.ProgramFiles) candidates.push(path.win32.join(env.ProgramFiles, 'Git', 'bin', 'bash.exe'));
  if (env['ProgramFiles(x86)']) candidates.push(path.win32.join(env['ProgramFiles(x86)'], 'Git', 'bin', 'bash.exe'));
  if (env.SystemDrive) {
    candidates.push(path.win32.join(env.SystemDrive, 'Program Files', 'Git', 'bin', 'bash.exe'));
    candidates.push(path.win32.join(env.SystemDrive, 'Program Files (x86)', 'Git', 'bin', 'bash.exe'));
  }

  for (const candidate of candidates) {
    if (candidate && exists(candidate)) {
      return JSON.stringify(candidate.replace(/\\/g, '/'));
    }
  }
  return null;
}

function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
  if (!settings || !settings.hooks || !absoluteRunner) return false;
  if (!opts) opts = {};
  const platform = opts.platform || process.platform;
  let changed = false;
  for (const entries of Object.values(settings.hooks)) {
    if (!Array.isArray(entries)) continue;
    for (const entry of entries) {
      if (!entry || !Array.isArray(entry.hooks)) continue;
      for (const h of entry.hooks) {
        if (!h || typeof h.command !== 'string') continue;
        let trimmed = h.command.trim();
        const hadPowerShellCallOperator = platform === 'win32' && /^&\s+/.test(trimmed);
        if (hadPowerShellCallOperator) {
          trimmed = trimmed.replace(/^&\s+/, '').trim();
        }
        // Match two runner forms:
        //   1. Legacy bare-node form: `node <script>` (#2979/#3002)
        //   2. Cellar-path form: `"/usr/local/Cellar/node/<v>/bin/node" <script>`
        //      or `"/opt/homebrew/Cellar/node/<v>/bin/node" <script>` (#3181)
        //
        // Both patterns use the same script-token capture group so the rewrite
        // is uniform. We detect the Cellar form by extracting the runner token
        // and running it through normalizeNodePath.
        //
        // The previous shape used `trimmed.includes(<filename>)` which would
        // false-positive on user-authored hooks whose path merely contained
        // a managed filename as a substring (e.g.
        // /home/me/scripts/wraps-gsd-check-update.js-and-more.js). #3002 CR.
        const m = trimmed.match(/^node\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/) ||
                  trimmed.match(/^("([^"]+)"|'([^']+)'|(\S+))\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/);
        if (!m) continue;

        let runnerToken, scriptToken, scriptPath;
        if (/^node\s+/.test(trimmed)) {
          // bare-node form
          runnerToken = 'node';
          scriptToken = m[1];
          scriptPath = m[2] || m[3] || m[4] || '';
        } else {
          // quoted/unquoted runner form — check whether runner is a Cellar path
          runnerToken = m[1];
          const runnerPath = (m[2] || m[3] || m[4] || '').replace(/\\/g, '/');
          const stableRunner = normalizeNodePath(runnerPath);
          // Process Cellar paths so they normalize to a stable symlink. On
          // Windows, already-absolute runners still flow through the projection
          // seam because some runtimes need additional wrapper policy while
          // others must stay shell-neutral (#3362, #3413).
          if (stableRunner === runnerPath && platform !== 'win32') continue;
          scriptToken = m[5];
          scriptPath = m[6] || m[7] || m[8] || '';
        }

        // Take the basename — match against MANAGED_HOOK_FILES by exact
        // equality, not substring containment. Handles both forward and
        // backslash separators (Windows).
        if (!isManagedHookBasename(scriptPath, { surface: 'settings-json' })) continue;

        const projectedCommand = projectLegacySettingsHookCommand({
          absoluteRunner,
          scriptPath,
          scriptToken,
          runtime: opts.runtime || 'generic',
          platform,
        });
        if (!projectedCommand) continue;

        // Skip only when the existing managed command already matches the
        // desired runtime-aware projected shape. This preserves Gemini's
        // required PowerShell prefix while still letting Claude strip stale
        // prefixes on reinstall (#3413).
        if (h.command === projectedCommand) continue;

        h.command = projectedCommand;
        changed = true;
      }
    }
  }
  return changed;
}

/**
 * Build the GSD-managed Codex SessionStart hook block for config.toml.
 *
 * Issue #3017: the previous shape inlined `command = "node ${path}"` which
 * fails under GUI/minimal-PATH runtimes where bare `node` doesn't resolve
 * (same failure mode as #2979 → fixed for settings.json by #3002, this
 * helper closes the gap for Codex's TOML hook surface).
 *
 * Returns null when `absoluteRunner` is null so callers can warn-and-skip
 * registration — emitting a broken bare-node hook is strictly worse than
 * not registering one (the user can re-run install once node is on PATH).
 *
 * @param {string} targetDir - Resolved absolute Codex config dir (e.g. ~/.codex).
 * @param {{ absoluteRunner: string|null, eol?: string }} opts
 *   absoluteRunner: result of resolveNodeRunner() — a JSON-stringified
 *   absolute node path with forward slashes (e.g. `"/usr/local/bin/node"`),
 *   or null when process.execPath was unavailable.
 *   eol: line ending to emit ('\n' or '\r\n') — caller passes
 *   detectLineEnding(configContent) so existing CRLF files stay CRLF.
 *   Defaults to '\n'.
 * @returns {string|null} The toml block to append, or null on missing runner.
 */
function buildCodexHookBlock(targetDir, opts) {
  const absoluteRunner = opts && opts.absoluteRunner;
  if (!absoluteRunner) return null;
  const eol = (opts && opts.eol) || '\n';
  const platform = (opts && opts.platform) || process.platform;
  const updateCheckScript = path.resolve(targetDir, 'hooks', 'gsd-check-update.js');
  const commandValue = projectCodexHookTomlCommand({
    absoluteRunner,
    scriptPath: updateCheckScript,
    platform,
  });
  return `${eol}# GSD Hooks${eol}` +
    `[[hooks.SessionStart]]${eol}` +
    `${eol}` +
    `[[hooks.SessionStart.hooks]]${eol}` +
    `type = "command"${eol}` +
    `command = "${commandValue}"${eol}`;
}

/**
 * Rewrite legacy bare-`node` managed-hook command lines in a Codex
 * config.toml string to use the absolute Node runner. Mirror of
 * rewriteLegacyManagedNodeHookCommands but for the toml surface (#3017).
 *
 * Only rewrites entries whose script basename matches CODEX_MANAGED_HOOK_BASENAMES
 * (basename equality, not substring containment) — user-authored bare-node
 * hooks pointing at scripts outside the managed allowlist are left alone.
 *
 * @param {string} content - Current config.toml contents.
 * @param {string|null} absoluteRunner - Result of resolveNodeRunner().
 * @returns {{ content: string, changed: boolean }}
 */
function rewriteLegacyCodexHookBlock(content, absoluteRunner, opts) {
  if (!content || !absoluteRunner) return { content, changed: false };
  const platform = (opts && opts.platform) || process.platform;
  let changed = false;
  // Match `command = "node <scriptToken>"` lines where scriptToken is
  // either an unquoted path (no spaces) or a toml-escaped quoted path.
  // The whole RHS is a toml-double-quoted string; interior quotes are \".
  // Examples we want to migrate:
  //   command = "node /Users/x/.codex/hooks/gsd-check-update.js"
  //   command = "node \"/Users/x/.codex/hooks/gsd-check-update.js\""
  // Examples we must leave alone:
  //   command = "\"/usr/local/bin/node\" \"/path/to/gsd-check-update.js\""  ← already absolute
  //   command = "node /home/me/my-custom.js"                                ← user-owned filename
  const updated = content.replace(
    /^(command\s*=\s*")node\s+((?:\\"[^"]+\\"|\S+))("\s*)$/gm,
    (full, prefix, scriptToken, suffix) => {
      // Extract the underlying script path from the captured token —
      // either the bare token or the decoded inner content of \"...\".
      const quoted = scriptToken.match(/^\\"([\s\S]+)\\"$/);
      let scriptPath = scriptToken;
      if (quoted) {
        try {
          scriptPath = String(parseTomlValue(`"${quoted[1]}"`, 0).value);
        } catch {
          scriptPath = quoted[1];
        }
      }
      if (!isManagedHookBasename(scriptPath, { surface: 'codex-toml' })) return full;
      const desiredCommand = projectCodexHookTomlCommand({
        absoluteRunner,
        scriptPath,
        platform,
      });
      const currentCommand = `${prefix}${scriptToken}${suffix}`.replace(/^(command\s*=\s*")|("\s*)$/g, '');
      if (currentCommand === desiredCommand) return full;
      changed = true;
      return `${prefix}${desiredCommand}${suffix}`;
    },
  );
  return { content: updated, changed };
}

/**
 * Generic reconcile helper: ensure hooks.json contains exactly one managed GSD
 * hook entry for `eventName`, while preserving all user-owned entries.
 *
 * Supports both known hooks.json shapes:
 *   1) { "<EventName>": [...] }
 *   2) { "hooks": { "<EventName>": [...] } }
 *
 * @param {string} targetDir - Codex config dir (e.g. ~/.codex or <project>/.codex).
 * @param {string} eventName - Codex hook event name (e.g. 'SessionStart', 'Stop').
 * @param {{ managedCommand?: string|null, commandWindows?: string|null, matcher?: string|null, timeout?: number|null }} opts
 *   managedCommand: POSIX hook command string to register, or null to remove.
 *   commandWindows: Windows .cmd shim path to emit as `commandWindows` field
 *     (#772). When provided, Codex uses this path on Windows and `managedCommand`
 *     on POSIX without needing per-platform config regeneration.
 *   matcher: optional Codex MatcherGroup pattern (e.g. 'Bash|Edit|Write').
 *   timeout: optional timeout in seconds.
 * @returns {{ changed: boolean, wrote: boolean, path: string }}
 */
function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
  const hooksJsonPath = path.join(targetDir, 'hooks.json');
  const managedCommand = typeof opts.managedCommand === 'string' ? opts.managedCommand : null;
  const commandWindows = typeof opts.commandWindows === 'string' ? opts.commandWindows : null;
  const matcher = typeof opts.matcher === 'string' ? opts.matcher : undefined;
  const timeout = typeof opts.timeout === 'number' ? opts.timeout : undefined;
  let parsed = {};
  let currentContent = null;
  if (fs.existsSync(hooksJsonPath)) {
    const raw = fs.readFileSync(hooksJsonPath, 'utf8');
    currentContent = raw;
    if (raw.trim()) {
      try {
        parsed = JSON.parse(raw);
      } catch (err) {
        throw new Error(`hooks.json parse failed: ${err && err.message ? err.message : String(err)}`);
      }
    }
  }
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};

  const usesNestedHooksObject =
    parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks);
  const hookTable = usesNestedHooksObject ? parsed.hooks : parsed;
  const eventEntries = Array.isArray(hookTable[eventName]) ? hookTable[eventName] : [];

  let removedLegacy = false;
  const sanitizedEntries = [];
  for (const entry of eventEntries) {
    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
    const originalHooks = Array.isArray(entry.hooks) ? entry.hooks : [];
    if (originalHooks.length === 0) {
      sanitizedEntries.push(entry);
      continue;
    }
    const keptHooks = originalHooks.filter((hook) => {
      const cmd = hook && typeof hook === 'object' ? hook.command : null;
      const managed = isManagedHookCommand(cmd, {
        surface: 'codex-hooks-json',
        includeLegacyAliases: true,
        configDir: targetDir,
      });
      if (managed) removedLegacy = true;
      return !managed;
    });
    if (keptHooks.length === 0) continue;
    const nextEntry = { ...entry, hooks: keptHooks };
    sanitizedEntries.push(nextEntry);
  }

  if (managedCommand) {
    const hookEntry = { type: 'command', command: managedCommand };
    // #772: emit commandWindows so Codex picks the .cmd shim on Windows and
    // the POSIX command on other platforms — without requiring per-OS config
    // regeneration. Sourced from HookHandlerConfig.command_windows field in
    // codex-rs/config/src/hook_config.rs (alias: commandWindows).
    if (commandWindows) hookEntry.commandWindows = commandWindows;
    if (timeout !== undefined) hookEntry.timeout = timeout;
    const newEntry = { hooks: [hookEntry] };
    if (matcher !== undefined) newEntry.matcher = matcher;
    sanitizedEntries.push(newEntry);
  }

  if (sanitizedEntries.length > 0) {
    hookTable[eventName] = sanitizedEntries;
  } else {
    delete hookTable[eventName];
  }
  if (usesNestedHooksObject) parsed.hooks = hookTable;

  const nextContent = `${JSON.stringify(parsed, null, 2)}\n`;
  const changed = currentContent !== nextContent;
  const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
  if (shouldWrite) {
    atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
  }

  return { changed: changed || removedLegacy, wrote: shouldWrite, path: hooksJsonPath };
}

/**
 * Reconcile the GSD-managed SessionStart hook entry in hooks.json.
 * Delegates to the generic reconcileCodexHooksJsonEvent helper.
 *
 * @param {string} targetDir
 * @param {{ managedCommand?: string|null, commandWindows?: string|null }} opts
 * @returns {{ changed: boolean, wrote: boolean, path: string }}
 */
function reconcileCodexHooksJsonSessionStart(targetDir, opts = {}) {
  return reconcileCodexHooksJsonEvent(targetDir, 'SessionStart', opts);
}

/**
 * Build a typed IR for the Codex hook .cmd shim used on Windows (#3426).
 *
 * On Windows, Codex runs hook commands from a PowerShell/cmd execution
 * environment. The previous command format was:
 *
 *   "C:/Program Files/nodejs/node.exe" "C:/path/.codex/hooks/gsd-check-update.js"
 *
 * This caused `bash.exe: bash.exe: cannot execute binary file` because
 * Codex's hook dispatch shell (Git Bash / MSYS) tried to POSIX-exec node.exe
 * (a Windows PE binary) via execvp(), which fails with ENOEXEC on Windows PE
 * binaries that the MSYS layer doesn't know how to fork-exec natively.
 *
 * Fix: write a .cmd shim (using the same CRLF .cmd shim pattern) whose
 * content is `@ECHO OFF / @SETLOCAL / @"node.exe" "script.js" %*`.
 * cmd.exe executes
 * .cmd natively via CreateProcess — no POSIX exec layer, no MSYS shebang
 * walk, no PE binary fork-exec failure.
 *
 * Returns the typed IR `{ invocation, cmdPath, hookCommand, render }` so
 * callers can assert on the structured shape (CONTRIBUTING.md L558–L565
 * IR-first discipline).  Returns null when absoluteRunnerToken is null so
 * callers can warn-and-skip instead of writing a broken hook.
 *
 * @param {string} scriptAbsPath - Absolute path to the .js hook script.
 * @param {string|null} absoluteRunnerToken - JSON-quoted absolute node path
 *   (result of resolveNodeRunner()), e.g. `"C:/Program Files/nodejs/node.exe"`.
 * @returns {{ invocation: { interpreter: string, target: string }, cmdPath: string, hookCommand: string, render: { cmd: () => string } }|null}
 */
function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
  if (!absoluteRunnerToken) return null;
  // absoluteRunnerToken is JSON-quoted (e.g. '"C:/path/node.exe"'). Unwrap to
  // get the raw interpreter path for the invocation record and render output.
  let interpreter;
  try {
    interpreter = JSON.parse(absoluteRunnerToken);
  } catch {
    interpreter = absoluteRunnerToken;
  }
  // Normalise to forward slashes for cross-shell safety (same as other Windows
  // hook path normalisations in this codebase).
  const targetAbs = scriptAbsPath.replace(/\\/g, '/');
  const scriptQuoted = JSON.stringify(targetAbs);
  // .cmd shim lives alongside the .js file, replacing the extension.
  const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
  // The hook command written to hooks.json is just the .cmd path (double-quoted
  // for spaces-in-path safety). cmd.exe executes .cmd files natively via
  // CreateProcess — no runner prefix required.
  const hookCommand = JSON.stringify(cmdPath.replace(/\\/g, '/'));
  const runnerQuoted = JSON.stringify(interpreter);
  return {
    invocation: { interpreter, target: scriptAbsPath },
    cmdPath,
    hookCommand,
    // Typed fields for IR-level assertions (CONTRIBUTING.md L558-L565).
    // These describe the render semantics in a structured way so tests can
    // assert on the generator contract without coupling to rendered text.
    eol: { cmd: '\r\n' },            // CRLF — canonical for cmd.exe .cmd files
    passthroughArgs: true,           // the shim forwards all args via %*
    render: {
      // Use CRLF line endings for strict cmd.exe compatibility (LF-only
      // .cmd files work in modern Windows but CRLF is the canonical format).
      cmd: () => `@ECHO OFF\r\n@SETLOCAL\r\n@${runnerQuoted} ${scriptQuoted} %*\r\n`,
    },
  };
}

/**
 * Ensure Codex hooks.json contains exactly one managed SessionStart
 * gsd-check-update hook entry, while preserving user-owned entries.
 *
 * Codex accepts hook config from hooks.json and config.toml. To avoid the
 * startup warning for mixed representations in the same layer, GSD now stores
 * the managed SessionStart hook in hooks.json and keeps config.toml for
 * feature flags / agent metadata only.
 *
 * Supports both known hooks.json shapes:
 *   1) { "SessionStart": [...] }
 *   2) { "hooks": { "SessionStart": [...] } }
 *
 * On Windows, writes a .cmd shim alongside the .js hook file and uses the
 * .cmd shim path as the hook command to avoid the `bash.exe: cannot execute
 * binary file` failure (#3426).
 *
 * #772: also emits `commandWindows` in the hook entry so that a
 * cross-platform hooks.json works on both POSIX and Windows without
 * requiring per-OS regeneration. Codex dispatches `commandWindows` on
 * Windows and `command` on other platforms (HookHandlerConfig in
 * codex-rs/config/src/hook_config.rs).
 *
 * @param {string} targetDir
 * @param {{ absoluteRunner: string|null, platform?: NodeJS.Platform }} opts
 * @returns {{ changed: boolean, wrote: boolean, path: string }}
 */
function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
  const platform = opts.platform || process.platform;
  const absoluteRunner = opts.absoluteRunner || null;
  const hooksJsonPath = path.join(targetDir, 'hooks.json');
  if (!absoluteRunner) return { changed: false, wrote: false, path: hooksJsonPath };

  // Normalize backslashes to forward slashes so isManagedHookCommand can
  // match stored commands against configDir on Windows CI runners where
  // path.resolve returns backslash paths but the stored command may use
  // forward slashes (or vice versa). Forward-slash paths are always valid on
  // Windows for both Node.js and Codex, so this normalization is safe for all
  // platforms. (#772 — same fix applied to ensureCodexHooksJsonEvent.)
  const scriptPath = path.resolve(targetDir, 'hooks', 'gsd-check-update.js').replace(/\\/g, '/');

  // #772: compute the Windows .cmd shim path cross-platform so that
  // `commandWindows` can be emitted in hooks.json regardless of the host OS.
  // The .cmd path is always the .js script path with extension replaced.
  const cmdShimPath = scriptPath.replace(/\.js$/, '.cmd');

  let managedCommand;
  if (platform === 'win32') {
    // #3426 fix: on Windows, write a .cmd shim and use its path as the hook
    // command. This avoids the MSYS bash.exe POSIX-exec failure when Codex's
    // hook dispatcher tries to run node.exe through the Git Bash exec layer.
    const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
    if (!shimIR) return { changed: false, wrote: false, path: hooksJsonPath };
    try {
      atomicWriteFileSync(shimIR.cmdPath, shimIR.render.cmd(), 'utf8');
    } catch (shimWriteErr) {
      // Shim write failed — do NOT fall back to the old "node.exe script.js"
      // command. That form triggers the `bash.exe: cannot execute binary file`
      // failure that #3426 exists to fix, so a silent fallback would silently
      // restore the original bug. Instead: warn loudly and skip the registration
      // for this runtime so the user sees an actionable message rather than a
      // successful install that fails at hook-dispatch time.
      const reason = shimWriteErr && shimWriteErr.message ? shimWriteErr.message : String(shimWriteErr);
      console.warn(
        `  ${yellow}⚠${reset}  Codex Windows hook NOT installed — .cmd shim write failed: ${reason}. ` +
          `Fix the write error (permissions? disk full?) and re-run the installer. ` +
          `Do NOT use the legacy node.exe command path — it triggers the #3426 bash.exe POSIX-exec failure.`,
      );
      return { changed: false, wrote: false, path: hooksJsonPath };
    }
    managedCommand = shimIR.hookCommand;
  } else {
    managedCommand = projectManagedHookCommand({
      absoluteRunner,
      scriptPath,
      runtime: 'codex',
      platform,
    });
  }

  if (!managedCommand) return { changed: false, wrote: false, path: hooksJsonPath };

  // #772: emit commandWindows — the .cmd shim path — but ONLY on Windows where
  // the shim was actually written. On POSIX, commandWindows is omitted to avoid
  // pointing Windows Codex at a non-existent .cmd file (the shim is only present
  // when install() ran natively on Windows and wrote it via buildCodexHookWindowsShimIR).
  const commandWindows = platform === 'win32'
    ? JSON.stringify(cmdShimPath.replace(/\\/g, '/'))
    : undefined;

  return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
}

/**
 * Ensure hooks.json contains exactly one managed GSD hook entry for the given
 * Codex event, wired to gsd-context-monitor.js. Preserves user-owned entries.
 *
 * Used for the new Codex events added in #772:
 *   SubagentStart — inject context / GSD_AGENT_NAME awareness at subagent open
 *   Stop          — post-session context headroom tracking
 *   PostToolUse   — mirror the Claude Code PostToolUse context monitor
 *
 * All three events are routed through gsd-context-monitor.js — the same hook
 * used for PostToolUse in the Claude Code baseline — so context-headroom
 * warnings surface at these key Codex session lifecycle moments.
 *
 * On Windows (#3426): writes a gsd-context-monitor.cmd shim alongside the .js
 * file and uses the .cmd path as the hook command — exactly the same fix as
 * SessionStart uses for gsd-check-update — to avoid the bash.exe POSIX-exec
 * failure when Codex's hook dispatcher tries to run node.exe through Git Bash.
 *
 * @param {string} targetDir
 * @param {string} eventName - One of 'SubagentStart', 'Stop', 'PostToolUse'.
 * @param {{ absoluteRunner: string|null, platform?: NodeJS.Platform }} opts
 * @returns {{ changed: boolean, wrote: boolean, path: string }}
 */
function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
  const platform = opts.platform || process.platform;
  const absoluteRunner = opts.absoluteRunner || null;
  const hooksJsonPath = path.join(targetDir, 'hooks.json');
  if (!absoluteRunner) return { changed: false, wrote: false, path: hooksJsonPath };

  // Normalize backslashes to forward slashes so that isManagedHookCommand can
  // match the stored command against configDir on Windows. path.resolve on
  // Windows returns backslash paths, but when platform is not 'win32'
  // (e.g. platform: 'linux' in a test running on a Windows CI runner),
  // projectManagedHookCommand does not normalize them — producing a mismatch
  // between the stored command and the configDir-based hook-dir prefix used
  // for deduplication. Forward-slash paths are always valid on Windows (Node.js
  // and Codex both accept them), so normalizing here is safe for all platforms.
  const scriptPath = path.resolve(targetDir, 'hooks', 'gsd-context-monitor.js').replace(/\\/g, '/');

  let managedCommand;
  if (platform === 'win32') {
    // #3426 fix pattern: on Windows, write a .cmd shim and use its path as the
    // hook command. The same bash.exe POSIX-exec failure that affects
    // gsd-check-update.js also affects gsd-context-monitor.js.
    const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
    if (!shimIR) return { changed: false, wrote: false, path: hooksJsonPath };
    try {
      atomicWriteFileSync(shimIR.cmdPath, shimIR.render.cmd(), 'utf8');
    } catch (shimWriteErr) {
      const reason = shimWriteErr && shimWriteErr.message ? shimWriteErr.message : String(shimWriteErr);
      console.warn(
        `  ${yellow}⚠${reset}  Codex Windows hook NOT installed — .cmd shim write failed for ${eventName}: ${reason}. ` +
          `Fix the write error (permissions? disk full?) and re-run the installer.`,
      );
      return { changed: false, wrote: false, path: hooksJsonPath };
    }
    managedCommand = shimIR.hookCommand;
  } else {
    managedCommand = projectManagedHookCommand({
      absoluteRunner,
      scriptPath,
      runtime: 'codex',
      platform,
    });
  }

  if (!managedCommand) return { changed: false, wrote: false, path: hooksJsonPath };
  return reconcileCodexHooksJsonEvent(targetDir, eventName, { managedCommand, timeout: 10 });
}

/**
 * Remove a GSD-managed event entry from hooks.json. Called during uninstall.
 *
 * @param {string} targetDir
 * @param {string} eventName
 */
function removeCodexHooksJsonEvent(targetDir, eventName) {
  return reconcileCodexHooksJsonEvent(targetDir, eventName, { managedCommand: null });
}

function removeCodexHooksJsonSessionStart(targetDir) {
  return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand: null });
}

/**
 * Build a hook command path using forward slashes for cross-platform compatibility.
 * On Windows, $HOME is not expanded by cmd.exe/PowerShell, so we use the actual path.
 *
 * @param {string} configDir - Resolved absolute config directory path
 * @param {string} hookName - Hook filename (e.g. 'gsd-statusline.js')
 * @param {{ portableHooks?: boolean, platform?: NodeJS.Platform, runtime?: string }} [opts] - Options
 *   portableHooks: when true, emit $HOME-relative paths instead of absolute paths.
 *   Safe for Linux/macOS global installs and WSL/Docker bind-mount scenarios.
 *   Not suitable for pure Windows (cmd.exe/PowerShell do not expand $HOME).
 *   platform: test injection for shell command formatting. Defaults to process.platform.
 *   runtime: target runtime name for shell projection policy.
 */
function buildHookCommand(configDir, hookName, opts) {
  if (!opts) opts = {};
  const platform = opts.platform || process.platform;
  const runtime = opts.runtime || 'generic';
  const isShellHook = hookName.endsWith('.sh');

  // #166: Claude Code executes these hook commands inside a bash context on
  // Windows, so wrapping `.sh` hooks with an explicit `bash.exe` path can
  // trigger `bash.exe: ... cannot execute binary file`. Emit only the quoted
  // script path for Claude on Windows.
  if (shellHookOmitsBashRunner({ platform, runtime, isShellHook })) {
    if (opts.portableHooks) {
      const portableBaseDir = projectPortableHookBaseDir({
        configDir,
        homeDir: os.homedir(),
      });
      return JSON.stringify(`${portableBaseDir}/hooks/${hookName}`);
    }
    return JSON.stringify(configDir.replace(/\\/g, '/') + '/hooks/' + hookName);
  }

  // POSIX .sh hooks run under PATH-resolved `bash`: POSIX guarantees /bin/sh
  // but not /bin/bash, and distros like NixOS do not ship /bin/bash by default.
  // Windows Codex launches hooks from PowerShell/cmd environments where bare
  // `bash` may not be on PATH, so resolve Git Bash explicitly or return null so
  // callers skip registration instead of installing a known-broken hook (#3393).
  // .js hooks still need the absolute node path because GUI-launched runtimes
  // start with a minimal PATH that may not include nvm/Homebrew/Volta node
  // binaries (#2979).
  const nodeRunner = resolveNodeRunner();
  const runner = isShellHook ? resolveBashRunner(opts) : nodeRunner;
  // Runner resolvers return null when the executable path is unavailable.
  // Fall through with null so callers can skip registration with a warning
  // instead of emitting a command that recreates the original hook failure.
  if (runner === null) return null;

  if (opts.portableHooks) {
    const portableBaseDir = projectPortableHookBaseDir({
      configDir,
      homeDir: os.homedir(),
    });
    return projectManagedHookCommand({
      absoluteRunner: runner,
      scriptPath: `${portableBaseDir}/hooks/${hookName}`,
      runtime: opts.runtime || 'generic',
      platform,
    });
  }

  // Default: absolute path with forward slashes (Windows-safe, fixes #2045/#2046).
  const hooksPath = configDir.replace(/\\/g, '/') + '/hooks/' + hookName;
  return projectManagedHookCommand({
    absoluteRunner: runner,
    scriptPath: hooksPath,
    runtime,
    platform,
  });
}

/**
 * Resolve the opencode config file path, preferring .jsonc if it exists.
 */
function resolveOpencodeConfigPath(configDir) {
  const jsoncPath = path.join(configDir, 'opencode.jsonc');
  if (fs.existsSync(jsoncPath)) {
    return jsoncPath;
  }
  return path.join(configDir, 'opencode.json');
}

/**
 * Resolve the Kilo config file path, preferring .jsonc if it exists.
 */
function resolveKiloConfigPath(configDir) {
  const jsoncPath = path.join(configDir, 'kilo.jsonc');
  if (fs.existsSync(jsoncPath)) {
    return jsoncPath;
  }
  return path.join(configDir, 'kilo.json');
}

/**
 * Strip JSONC comments (// and /* *​/) from a string to produce valid JSON.
 * Handles comments inside strings correctly (does not strip them).
 */
function stripJsonComments(text) {
  let result = '';
  let i = 0;
  let inString = false;
  let stringChar = '';
  while (i < text.length) {
    // Handle string literals — don't strip comments inside strings
    if (inString) {
      if (text[i] === '\\') {
        result += text[i] + (text[i + 1] || '');
        i += 2;
        continue;
      }
      if (text[i] === stringChar) {
        inString = false;
      }
      result += text[i];
      i++;
      continue;
    }
    // Start of string
    if (text[i] === '"' || text[i] === "'") {
      inString = true;
      stringChar = text[i];
      result += text[i];
      i++;
      continue;
    }
    // Line comment
    if (text[i] === '/' && text[i + 1] === '/') {
      // Skip to end of line
      while (i < text.length && text[i] !== '\n') i++;
      continue;
    }
    // Block comment
    if (text[i] === '/' && text[i + 1] === '*') {
      i += 2;
      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
      i += 2; // skip closing */
      continue;
    }
    result += text[i];
    i++;
  }
  // Remove trailing commas before } or ] (common in JSONC)
  return result.replace(/,\s*([}\]])/g, '$1');
}

/**
 * Read and parse settings.json, returning empty object if it doesn't exist.
 * Supports JSONC (JSON with comments) — many CLI tools allow comments in
 * their settings files, so we strip them before parsing to avoid silent
 * data loss from JSON.parse failures.
 */
function readSettings(settingsPath) {
  if (fs.existsSync(settingsPath)) {
    try {
      const raw = fs.readFileSync(settingsPath, 'utf8');
      // Try standard JSON first (fast path)
      try {
        return JSON.parse(raw);
      } catch {
        // Fall back to JSONC stripping
        return JSON.parse(stripJsonComments(raw));
      }
    } catch (e) {
      // If even JSONC stripping fails, warn instead of silently returning {}
      console.warn('  ' + yellow + '⚠' + reset + '  Warning: Could not parse ' + settingsPath + ' — file may be malformed. Existing settings preserved.');
      return null;
    }
  }
  return {};
}

/**
 * Write settings.json with proper formatting
 */
function writeSettings(settingsPath, settings) {
  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
}

/**
 * Read model_overrides from ~/.gsd/defaults.json at install time.
 * Returns an object mapping agent names to model IDs, or null if the file
 * doesn't exist or has no model_overrides entry.
 * Used by Codex TOML and OpenCode agent file generators to embed per-agent
 * model assignments so that model_overrides is respected on non-Claude runtimes (#2256).
 */
function readGsdGlobalModelOverrides() {
  try {
    const defaultsPath = path.join(os.homedir(), '.gsd', 'defaults.json');
    if (!fs.existsSync(defaultsPath)) return null;
    const raw = fs.readFileSync(defaultsPath, 'utf-8');
    const parsed = JSON.parse(raw);
    const overrides = parsed.model_overrides;
    if (!overrides || typeof overrides !== 'object') return null;
    return overrides;
  } catch {
    return null;
  }
}

/**
 * Effective per-agent model_overrides for the Codex / OpenCode install paths.
 *
 * Merges `~/.gsd/defaults.json` (global) with per-project
 * `<project>/.planning/config.json`. Per-project keys win on conflict so a
 * user can tune a single agent's model in one repo without re-setting the
 * global defaults for every other repo. Non-conflicting keys from both
 * sources are preserved.
 *
 * This is the fix for #2256: both adapters previously read only the global
 * file, so a per-project `model_overrides` (the common case the reporter
 * described — a per-project override for `gsd-codebase-mapper` in
 * `.planning/config.json`) was silently dropped and child agents inherited
 * the session default.
 *
 * `targetDir` is the consuming runtime's install root (e.g. `~/.codex` for
 * a global install, or `<project>/.codex` for a local install). We walk up
 * from there looking for `.planning/` so both cases resolve the correct
 * project root. When `targetDir` is null/undefined only the global file is
 * consulted (matches prior behavior for code paths that have no project
 * context).
 *
 * Returns a plain `{ agentName: modelId }` object, or `null` when neither
 * source defines `model_overrides`.
 */
function readGsdEffectiveModelOverrides(targetDir = null) {
  const global = readGsdGlobalModelOverrides();

  let projectOverrides = null;
  if (targetDir) {
    let probeDir = path.resolve(targetDir);
    for (let depth = 0; depth < 8; depth += 1) {
      const candidate = path.join(probeDir, '.planning', 'config.json');
      if (fs.existsSync(candidate)) {
        try {
          const parsed = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
          if (parsed && typeof parsed === 'object' && parsed.model_overrides
              && typeof parsed.model_overrides === 'object') {
            projectOverrides = parsed.model_overrides;
          }
        } catch {
          // Malformed config.json — fall back to global; readGsdRuntimeProfileResolver
          // surfaces a parse warning via _readGsdConfigFile already.
        }
        break;
      }
      const parent = path.dirname(probeDir);
      if (parent === probeDir) break;
      probeDir = parent;
    }
  }

  if (!global && !projectOverrides) return null;
  // Per-project wins on conflict; preserve non-conflicting global keys.
  return { ...(global || {}), ...(projectOverrides || {}) };
}

/**
 * #443 — Read the merged `effort` config block for install-time effort resolution.
 *
 * Probes the same config sources as readGsdRuntimeProfileResolver (per-project
 * `.planning/config.json` wins over `~/.gsd/defaults.json`) but extracts the
 * `effort` object instead of the model-profile fields.
 *
 * Returns the merged `effort` object or null when neither source defines one.
 * The caller can pass this to resolveInstallTimeEffort() which is pure and
 * requires no filesystem access beyond what this helper already performs.
 *
 * @param {string|null} targetDir  Runtime install root (walks up to find .planning/).
 * @returns {object|null}
 */
function readGsdEffectiveEffortConfig(targetDir = null) {
  const homeDefaults = _readGsdConfigFile(
    path.join(os.homedir(), '.gsd', 'defaults.json'),
    '~/.gsd/defaults.json'
  );

  let projectConfig = null;
  if (targetDir) {
    let probeDir = path.resolve(targetDir);
    for (let depth = 0; depth < 8; depth += 1) {
      const candidate = path.join(probeDir, '.planning', 'config.json');
      if (fs.existsSync(candidate)) {
        projectConfig = _readGsdConfigFile(candidate, '.planning/config.json');
        break;
      }
      const parent = path.dirname(probeDir);
      if (parent === probeDir) break;
      probeDir = parent;
    }
  }

  const homeEffort = (homeDefaults && homeDefaults.effort && typeof homeDefaults.effort === 'object' && !Array.isArray(homeDefaults.effort))
    ? homeDefaults.effort
    : null;
  const projectEffort = (projectConfig && projectConfig.effort && typeof projectConfig.effort === 'object' && !Array.isArray(projectConfig.effort))
    ? projectConfig.effort
    : null;

  if (!homeEffort && !projectEffort) return null;

  // Per-project wins on conflict within each sub-field. Merge field-by-field so
  // a project config that only sets agent_overrides still inherits global
  // routing_tier_defaults and default.
  return {
    ...(homeEffort || {}),
    ...(projectEffort || {}),
    // Deep-merge agent_overrides (project wins per-key)
    agent_overrides: {
      ...((homeEffort && homeEffort.agent_overrides) || {}),
      ...((projectEffort && projectEffort.agent_overrides) || {}),
    },
  };
}


/**
 * #443 — Resolve install-time effort for a given agent, using the same
 * precedence chain as resolveEffortInternal() in core.cjs, but operating
 * on a pre-loaded effortCfg object (no loadConfig side-effects at install).
 *
 * Precedence (mirrors resolveEffortInternal):
 *   1. effortCfg.agent_overrides[agentName]
 *   2. effortCfg.routing_tier_defaults[agentTier]  (if effortCfg present)
 *      — OR manifest tier defaults when effortCfg is null
 *   3. effortCfg.default
 *   4. 'high' (hardcoded fallback)
 *
 * @param {object|null} effortCfg   Result of readGsdEffectiveEffortConfig().
 * @param {string} agentName        e.g. 'gsd-planner'
 * @returns {string}                Universal effort string (low/medium/high/xhigh/max/minimal)
 */
function resolveInstallTimeEffort(effortCfg, agentName) {
  // Validates each candidate against the canonical EFFORT_SET (sourced once
  // from core.cjs) before accepting it, mirroring resolveEffortInternal exactly.
  // Invalid values fall through to the next precedence layer; final fallback 'high'.

  // Step 1: agent_overrides
  if (effortCfg) {
    const ao = effortCfg.agent_overrides;
    if (ao && typeof ao === 'object' && !Array.isArray(ao)) {
      const v = ao[agentName];
      if (typeof v === 'string' && GSD_EFFORT_SET.has(v)) return v;
    }
  }

  // Step 2: routing_tier_defaults keyed by the agent's catalog tier
  const { AGENT_DEFAULT_TIERS, EFFORT_MANIFEST_TIER_DEFAULTS, EFFORT_MANIFEST_DEFAULT } = _getGsdEffortCatalog();
  const agentTier = AGENT_DEFAULT_TIERS[agentName];
  if (agentTier) {
    if (effortCfg && effortCfg.routing_tier_defaults &&
        typeof effortCfg.routing_tier_defaults === 'object' &&
        !Array.isArray(effortCfg.routing_tier_defaults)) {
      const v = effortCfg.routing_tier_defaults[agentTier];
      if (typeof v === 'string' && GSD_EFFORT_SET.has(v)) return v;
    } else if (!effortCfg) {
      // No effort config — use manifest tier defaults
      const v = EFFORT_MANIFEST_TIER_DEFAULTS[agentTier];
      if (typeof v === 'string' && GSD_EFFORT_SET.has(v)) return v;
    }
    // effortCfg exists but has no routing_tier_defaults — fall through
  }

  // Step 3: effort.default
  if (effortCfg) {
    const d = effortCfg.default;
    if (typeof d === 'string' && GSD_EFFORT_SET.has(d)) return d;
  }

  // Step 4: manifest default (sourced from config-defaults.manifest.json effort.default)
  // If even the manifest default is invalid, fall back to 'high'.
  if (typeof EFFORT_MANIFEST_DEFAULT === 'string' && GSD_EFFORT_SET.has(EFFORT_MANIFEST_DEFAULT)) {
    return EFFORT_MANIFEST_DEFAULT;
  }
  return 'high';
}

/**
 * #443 — Inject `effort: <value>` into YAML frontmatter of a Claude .md agent
 * file in a newline-agnostic way (LF and CRLF source files are both handled).
 *
 * The function:
 *   - Detects the file's EOL (CRLF if the first `---` line ends with \r\n,
 *     otherwise LF).
 *   - Skips injection if an `effort:` key already exists in the frontmatter
 *     (idempotent).
 *   - Inserts `effort: <value>` immediately before the closing `---` delimiter,
 *     using the same EOL as the surrounding frontmatter so the output file
 *     stays EOL-consistent.
 *   - Returns the original content unchanged when no YAML frontmatter is found.
 *
 * @param {string} content      Raw file content (may have LF or CRLF endings).
 * @param {string} effortValue  Rendered effort string, e.g. "xhigh".
 * @returns {string}            Updated content with `effort:` injected, or the
 *                              original content when no frontmatter is found.
 */
function injectEffortFrontmatter(content, effortValue) {
  // Detect the dominant EOL from the first line (the opening `---`).
  // If the very first `---` is followed by \r\n, treat the whole file as CRLF.
  const eol = /^---\r\n/.test(content) ? '\r\n' : '\n';

  // Build a frontmatter-matching regex that tolerates an optional \r before
  // each \n, so we handle both LF and CRLF files without needing to normalise
  // the whole content.
  //
  // Breakdown:
  //   ^---\r?\n        — opening delimiter (with optional \r)
  //   ([\s\S]*?)       — frontmatter body (non-greedy)
  //   ^---\r?$         — closing delimiter line (optional \r, $ before \n in
  //                       multiline mode)
  //   (\r?\n|$)        — newline after closing --- (or end of string)
  //
  // The `m` flag makes ^ / $ match at every line boundary.
  const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
  const match = fmRe.exec(content);
  if (!match) return content; // no YAML frontmatter — leave unchanged

  // Idempotency guard: don't insert a second effort: line.
  const fmBody = match[1]; // content between the two `---` lines
  if (/^effort:/m.test(fmBody)) return content;

  // Locate the exact position of the closing `---` line so we can insert
  // before it using a simple string splice (avoids re-running the regex and
  // avoids any edge-cases with $ matching \r differently per engine).
  const closeIdx = match.index + 4 + fmBody.length; // 4 = len("---\n") (opening)
  // Actually compute based on the full match start + captured group length:
  // match[0] = full frontmatter block; match.index = start of that block.
  // The closing `---` starts at: match.index + ("---" + eol).length + fmBody.length
  const openLen = 3 + eol.length; // "---" + eol
  const closingStart = match.index + openLen + fmBody.length;

  const before = content.slice(0, closingStart);
  const after = content.slice(closingStart);
  return `${before}effort: ${effortValue}${eol}${after}`;
}

/**
 * #2517 — Read a single GSD config file (defaults.json or per-project
 * config.json) into a plain object, returning null on missing/empty files
 * and warning to stderr on JSON parse failures so silent corruption can't
 * mask broken configs (review finding #5).
 */
function _readGsdConfigFile(absPath, label) {
  if (!fs.existsSync(absPath)) return null;
  let raw;
  try {
    raw = fs.readFileSync(absPath, 'utf-8');
  } catch (err) {
    process.stderr.write(`gsd: warning — could not read ${label} (${absPath}): ${err.message}\n`);
    return null;
  }
  try {
    return JSON.parse(raw);
  } catch (err) {
    process.stderr.write(`gsd: warning — invalid JSON in ${label} (${absPath}): ${err.message}\n`);
    return null;
  }
}

/**
 * #2517 — Build a runtime-aware tier resolver for the install path.
 *
 * Probes BOTH per-project `<targetDir>/.planning/config.json` AND
 * `~/.gsd/defaults.json`, with per-project keys winning over global. This
 * matches `loadConfig`'s precedence and is the only way the PR's headline claim
 * — "set runtime in .planning/config.json and the Codex TOML emit picks it up"
 * — actually holds end-to-end (review finding #1).
 *
 * `targetDir` should be the consuming runtime's install root — install code
 * passes `path.dirname(<runtime root>)` so `.planning/config.json` resolves
 * relative to the user's project. When `targetDir` is null/undefined, only the
 * global defaults are consulted.
 *
 * Returns null if no `runtime` is configured (preserves prior behavior — only
 * model_overrides is embedded, no tier/reasoning-effort inference). Returns
 * null when `model_profile` is `inherit` so the literal alias passes through
 * unchanged.
 *
 * Returns { runtime, resolve(agentName) -> { model, reasoning_effort? } | null }
 */
function readGsdRuntimeProfileResolver(targetDir = null) {
  const homeDefaults = _readGsdConfigFile(
    path.join(os.homedir(), '.gsd', 'defaults.json'),
    '~/.gsd/defaults.json'
  );

  // Per-project config probe. Resolve the project root by walking up from
  // targetDir until we hit a `.planning/` directory; this covers both the
  // common case (caller passes the project root) and the case where caller
  // passes a nested install dir like `<root>/.codex/`.
  let projectConfig = null;
  if (targetDir) {
    let probeDir = path.resolve(targetDir);
    for (let depth = 0; depth < 8; depth += 1) {
      const candidate = path.join(probeDir, '.planning', 'config.json');
      if (fs.existsSync(candidate)) {
        projectConfig = _readGsdConfigFile(candidate, '.planning/config.json');
        break;
      }
      const parent = path.dirname(probeDir);
      if (parent === probeDir) break;
      probeDir = parent;
    }
  }

  // Per-project wins. Only fall back to ~/.gsd/defaults.json when the project
  // didn't set the field. Field-level merge (not whole-object replace) so a
  // user can keep `runtime` global while overriding only `model_profile` per
  // project, and vice versa.
  const merged = {
    runtime:
      (projectConfig && projectConfig.runtime) ||
      (homeDefaults && homeDefaults.runtime) ||
      null,
    model_profile:
      (projectConfig && projectConfig.model_profile) ||
      (homeDefaults && homeDefaults.model_profile) ||
      'balanced',
    model_profile_overrides:
      (projectConfig && projectConfig.model_profile_overrides) ||
      (homeDefaults && homeDefaults.model_profile_overrides) ||
      null,
  };

  if (!merged.runtime) return null;

  const profile = String(merged.model_profile).toLowerCase();
  if (profile === 'inherit') return null;

  return {
    runtime: merged.runtime,
    resolve(agentName) {
      const agentModels = GSD_MODEL_PROFILES[agentName];
      if (!agentModels) return null;
      const tier = agentModels[profile] || agentModels.balanced;
      if (!tier) return null;
      return gsdResolveTierEntry({
        runtime: merged.runtime,
        tier,
        overrides: merged.model_profile_overrides,
      });
    },
  };
}

// Cache for attribution settings (populated once per runtime during install)
const attributionCache = new Map();

/**
 * Get commit attribution setting for a runtime
 * @param {string} runtime - 'claude', 'opencode', 'gemini', 'codex', or 'copilot'
 * @returns {null|undefined|string} null = remove, undefined = keep default, string = custom
 */
function getCommitAttribution(runtime) {
  // Return cached value if available
  if (attributionCache.has(runtime)) {
    return attributionCache.get(runtime);
  }

  let result;

  if (runtime === 'opencode' || runtime === 'kilo') {
    const resolveConfigPath = runtime === 'opencode'
      ? resolveOpencodeConfigPath
      : resolveKiloConfigPath;
    const config = readSettings(resolveConfigPath(getGlobalConfigDir(runtime, null)));
    result = (config && config.disable_ai_attribution === true) ? null : undefined;
  } else if (runtime === 'gemini') {
    // Gemini: check gemini settings.json for attribution config
    const settings = readSettings(path.join(getGlobalConfigDir('gemini', explicitConfigDir), 'settings.json'));
    if (!settings || !settings.attribution || settings.attribution.commit === undefined) {
      result = undefined;
    } else if (settings.attribution.commit === '') {
      result = null;
    } else {
      result = settings.attribution.commit;
    }
  } else if (runtime === 'claude') {
    // Claude Code
    const settings = readSettings(path.join(getGlobalConfigDir('claude', explicitConfigDir), 'settings.json'));
    if (!settings || !settings.attribution || settings.attribution.commit === undefined) {
      result = undefined;
    } else if (settings.attribution.commit === '') {
      result = null;
    } else {
      result = settings.attribution.commit;
    }
  } else {
    // Codex and Copilot currently have no attribution setting equivalent
    result = undefined;
  }

  // Cache and return
  attributionCache.set(runtime, result);
  return result;
}

/**
 * Process Co-Authored-By lines based on attribution setting
 * @param {string} content - File content to process
 * @param {null|undefined|string} attribution - null=remove, undefined=keep, string=replace
 * @returns {string} Processed content
 */
function processAttribution(content, attribution) {
  if (attribution === null) {
    // Remove Co-Authored-By lines and the preceding blank line
    return content.replace(/(\r?\n){2}Co-Authored-By:.*$/gim, '');
  }
  if (attribution === undefined) {
    return content;
  }
  // Replace with custom attribution (escape $ to prevent backreference injection)
  const safeAttribution = attribution.replace(/\$/g, '$$$$');
  return content.replace(/Co-Authored-By:.*$/gim, `Co-Authored-By: ${safeAttribution}`);
}

/**
 * Convert Claude Code frontmatter to opencode format
 * - Converts 'allowed-tools:' array to 'permission:' object
 * @param {string} content - Markdown file content with YAML frontmatter
 * @returns {string} - Content with converted frontmatter
 */
// Color name to hex mapping for opencode compatibility
const colorNameToHex = {
  cyan: '#00FFFF',
  red: '#FF0000',
  green: '#00FF00',
  blue: '#0000FF',
  yellow: '#FFFF00',
  magenta: '#FF00FF',
  orange: '#FFA500',
  purple: '#800080',
  pink: '#FFC0CB',
  white: '#FFFFFF',
  black: '#000000',
  gray: '#808080',
  grey: '#808080',
};

// Tool name mapping from Claude Code to OpenCode
// OpenCode uses lowercase tool names; special mappings for renamed tools
const claudeToOpencodeTools = {
  AskUserQuestion: 'question',
  SlashCommand: 'skill',
  TodoWrite: 'todowrite',
  WebFetch: 'webfetch',
  WebSearch: 'websearch',  // Plugin/MCP - keep for compatibility
};

// Tool name mapping from Claude Code to Gemini CLI
// Gemini CLI uses snake_case built-in tool names
const claudeToGeminiTools = {
  Read: 'read_file',
  Write: 'write_file',
  Edit: 'replace',
  Bash: 'run_shell_command',
  Glob: 'glob',
  Grep: 'search_file_content',
  WebSearch: 'google_web_search',
  WebFetch: 'web_fetch',
  TodoWrite: 'write_todos',
};

// Tool name mapping from Claude/GSD agents to Kimi CLI module paths.
// Kimi custom agent YAML requires fully-qualified module paths.
const claudeToKimiTools = {
  Read: 'kimi_cli.tools.file:ReadFile',
  ReadFile: 'kimi_cli.tools.file:ReadFile',
  Write: 'kimi_cli.tools.file:WriteFile',
  WriteFile: 'kimi_cli.tools.file:WriteFile',
  Edit: 'kimi_cli.tools.file:StrReplaceFile',
  MultiEdit: 'kimi_cli.tools.file:StrReplaceFile',
  StrReplaceFile: 'kimi_cli.tools.file:StrReplaceFile',
  Bash: 'kimi_cli.tools.shell:Shell',
  Shell: 'kimi_cli.tools.shell:Shell',
  Grep: 'kimi_cli.tools.file:Grep',
  Glob: 'kimi_cli.tools.file:Glob',
  Agent: 'kimi_cli.tools.agent:Agent',
  Task: 'kimi_cli.tools.agent:Agent',
  AskUserQuestion: 'kimi_cli.tools.ask_user:AskUserQuestion',
  TodoWrite: 'kimi_cli.tools.todo:SetTodoList',
  SetTodoList: 'kimi_cli.tools.todo:SetTodoList',
  WebSearch: 'kimi_cli.tools.web:SearchWeb',
  SearchWeb: 'kimi_cli.tools.web:SearchWeb',
  WebFetch: 'kimi_cli.tools.web:FetchURL',
  FetchURL: 'kimi_cli.tools.web:FetchURL',
  ReadMediaFile: 'kimi_cli.tools.file:ReadMediaFile',
  TaskList: 'kimi_cli.tools.background:TaskList',
  TaskOutput: 'kimi_cli.tools.background:TaskOutput',
  TaskStop: 'kimi_cli.tools.background:TaskStop',
};

/**
 * Convert a Claude Code tool name to OpenCode format
 * - Applies special mappings (AskUserQuestion -> question, etc.)
 * - Converts to lowercase (except MCP tools which keep their format)
 */
function convertToolName(claudeTool) {
  // Check for special mapping first
  if (claudeToOpencodeTools[claudeTool]) {
    return claudeToOpencodeTools[claudeTool];
  }
  // MCP tools (mcp__*) keep their format
  if (claudeTool.startsWith('mcp__')) {
    return claudeTool;
  }
  // Default: convert to lowercase
  return claudeTool.toLowerCase();
}

/**
 * Convert a Claude Code tool name to Gemini CLI format
 * - Applies Claude→Gemini mapping (Read→read_file, Bash→run_shell_command, etc.)
 * - Filters out MCP tools (mcp__*) — they are auto-discovered at runtime in Gemini
 * - Filters out Task/Agent — agents are auto-registered as tools in Gemini
 * @returns {string|null} Gemini tool name, or null if tool should be excluded
 */
function convertGeminiToolName(claudeTool) {
  // MCP tools: exclude — auto-discovered from mcpServers config at runtime
  if (claudeTool.startsWith('mcp__')) {
    return null;
  }
  // Task/Agent: exclude — agents are auto-registered as callable tools.
  // AskUserQuestion: exclude — Gemini CLI does not expose an ask_user tool;
  // emitting it causes frontmatter validation errors (#3362).
  if (
    claudeTool === 'Task' ||
    claudeTool === 'Agent' ||
    claudeTool === 'AskUserQuestion' ||
    claudeTool === 'ask_user'
  ) {
    return null;
  }
  // Check for explicit mapping
  if (claudeToGeminiTools[claudeTool]) {
    return claudeToGeminiTools[claudeTool];
  }
  // Default: lowercase
  return claudeTool.toLowerCase();
}

function createKimiToolDiagnostic(reason, tool, source = null) {
  const isMcp = reason === 'mcp_managed';
  return {
    level: 'warning',
    code: isMcp ? 'kimi_mcp_tool_excluded' : 'kimi_unsupported_tool',
    reason,
    message: isMcp
      ? `MCP-managed tool '${tool}' is configured outside Kimi agent YAML.`
      : `Tool '${tool}' is not supported by the Kimi tool mapper.`,
    value: tool,
    source,
  };
}

/**
 * Convert a Claude/GSD tool name to a Kimi CLI module path.
 * @returns {string|null} Kimi module path, or null when excluded/unsupported.
 */
function convertKimiToolName(claudeTool) {
  const tool = String(claudeTool || '').trim();
  if (!tool) return null;
  if (tool.startsWith('mcp__')) return null;
  return claudeToKimiTools[tool] || null;
}

function mapClaudeToolsToKimiTools(claudeTools, options = {}) {
  const diagnostics = [];
  const tools = [];
  const seen = new Set();
  const source = options && Object.prototype.hasOwnProperty.call(options, 'source')
    ? options.source
    : null;

  for (const rawTool of Array.isArray(claudeTools) ? claudeTools : []) {
    const tool = String(rawTool || '').trim();
    if (!tool) continue;

    if (tool.startsWith('mcp__')) {
      diagnostics.push(createKimiToolDiagnostic('mcp_managed', tool, source));
      continue;
    }

    const kimiTool = convertKimiToolName(tool);
    if (!kimiTool) {
      diagnostics.push(createKimiToolDiagnostic('unsupported_tool', tool, source));
      continue;
    }

    if (!seen.has(kimiTool)) {
      seen.add(kimiTool);
      tools.push(kimiTool);
    }
  }

  return { tools, diagnostics };
}

const claudeToKiloAgentPermissions = {
  Read: 'read',
  Write: 'edit',
  Edit: 'edit',
  Bash: 'bash',
  Grep: 'grep',
  Glob: 'glob',
  Task: 'task',
  WebFetch: 'webfetch',
  WebSearch: 'websearch',
  TodoWrite: 'todowrite',
  AskUserQuestion: 'question',
  SlashCommand: 'skill',
};

const kiloAgentPermissionOrder = [
  'read',
  'edit',
  'bash',
  'grep',
  'glob',
  'task',
  'webfetch',
  'websearch',
  'skill',
  'question',
  'todowrite',
  'list',
  'codesearch',
  'lsp',
];

function convertClaudeToKiloPermissionTool(claudeTool) {
  return claudeToKiloAgentPermissions[claudeTool] || null;
}

function buildKiloAgentPermissionBlock(claudeTools) {
  const allowedPermissions = new Set();

  for (const tool of claudeTools) {
    const mapped = convertClaudeToKiloPermissionTool(tool);
    if (mapped) {
      allowedPermissions.add(mapped);
    }
  }

  const lines = ['permission:'];
  for (const permission of kiloAgentPermissionOrder) {
    lines.push(`  ${permission}: ${allowedPermissions.has(permission) ? 'allow' : 'deny'}`);
  }

  return lines;
}

function escapeRegExp(value) {
  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

function replaceRelativePathReference(content, fromPath, toPath) {
  const escapedPath = escapeRegExp(fromPath);
  return content.replace(
    new RegExp(`(^|[^A-Za-z0-9_./-])${escapedPath}`, 'g'),
    (_, prefix) => `${prefix}${toPath}`,
  );
}

/**
 * Convert a Claude Code tool name to GitHub Copilot format.
 * - Applies explicit mapping from claudeToCopilotTools
 * - Handles mcp__context7__* prefix → io.github.upstash/context7/*
 * - Falls back to lowercase for unknown tools
 */
function convertCopilotToolName(claudeTool) {
  // mcp__context7__* wildcard → io.github.upstash/context7/*
  if (claudeTool.startsWith('mcp__context7__')) {
    return 'io.github.upstash/context7/' + claudeTool.slice('mcp__context7__'.length);
  }
  // Check explicit mapping
  if (claudeToCopilotTools[claudeTool]) {
    return claudeToCopilotTools[claudeTool];
  }
  // mcp__{tavily,ref,jina,exa,firecrawl}__* use the generic MCP passthrough like exa/firecrawl;
  // add explicit Copilot registry mappings when the io.github ids are confirmed (#657 follow-up)
  // Default: lowercase
  return claudeTool.toLowerCase();
}

/**
 * Apply Copilot-specific content conversion — CONV-06 (paths) + CONV-07 (command names).
 * Path mappings depend on install mode:
 *   Global: ~/.claude/ → ~/.copilot/, ./.claude/ → ./.github/
 *   Local:  ~/.claude/ → ./.github/, ./.claude/ → ./.github/
 * Applied to ALL Copilot content (skills, agents, engine files).
 * @param {string} content - Source content to convert
 * @param {boolean} [isGlobal=false] - Whether this is a global install
 */
function convertClaudeToCopilotContent(content, isGlobal = false) {
  let c = content;
  // CONV-06: Path replacement — most specific first to avoid substring matches.
  // Handle both `~/.claude/foo` (trailing slash) and bare `~/.claude` forms in
  // one pass via a capture group, matching the approach used by Antigravity,
  // OpenCode, Kilo, and Codex converters (issue #2545).
  if (isGlobal) {
    c = c.replace(/\$HOME\/\.claude(\/|\b)/g, '$HOME/.copilot$1');
    c = c.replace(/~\/\.claude(\/|\b)/g, '~/.copilot$1');
  } else {
    c = c.replace(/\$HOME\/\.claude\//g, '.github/');
    c = c.replace(/~\/\.claude\//g, '.github/');
    c = c.replace(/\$HOME\/\.claude\b/g, '.github');
    c = c.replace(/~\/\.claude\b/g, '.github');
  }
  c = c.replace(/\.\/\.claude\//g, './.github/');
  c = c.replace(/\.claude\//g, '.github/');
  // CONV-07: Command name conversion (all gsd: references → gsd-)
  c = c.replace(/gsd:/g, 'gsd-');
  // Runtime-neutral agent name replacement (#766)
  c = neutralizeAgentReferences(c, 'copilot-instructions.md');
  return c;
}

/**
 * Convert a Claude command (.md) to a Copilot skill (SKILL.md).
 * Transforms frontmatter only — body passes through with CONV-06/07 applied.
 * Skills keep original tool names (no mapping) per CONTEXT.md decision.
 */
function convertClaudeCommandToCopilotSkill(content, skillName, isGlobal = false) {
  const converted = convertClaudeToCopilotContent(content, isGlobal);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const argumentHint = extractFrontmatterField(frontmatter, 'argument-hint');
  const agent = extractFrontmatterField(frontmatter, 'agent');

  // CONV-02: Extract allowed-tools YAML multiline list → comma-separated string
  const toolsMatch = frontmatter.match(/^allowed-tools:\s*\n((?:\s+-\s+.+\n?)*)/m);
  let toolsLine = '';
  if (toolsMatch) {
    const tools = toolsMatch[1].match(/^\s+-\s+(.+)/gm);
    if (tools) {
      toolsLine = tools.map(t => t.replace(/^\s+-\s+/, '').trim()).join(', ');
    }
  }

  // Reconstruct frontmatter in Copilot format
  // #2876: descriptions starting with a YAML flow indicator (`[BETA] …`,
  // `{ … }`, `*ref`, `&anchor`, etc.) parse as flow sequences/mappings and
  // crash gh-copilot's frontmatter loader. Always quote so any leading
  // character is parser-safe.
  let fm = `---\nname: ${skillName}\ndescription: ${yamlQuote(description)}\n`;
  if (argumentHint) fm += `argument-hint: ${yamlQuote(argumentHint)}\n`;
  if (agent) fm += `agent: ${agent}\n`;
  if (toolsLine) fm += `allowed-tools: ${toolsLine}\n`;
  fm += '---';

  return `${fm}\n${body}`;
}

/**
 * Map a skill directory name (gsd-<cmd>) to the frontmatter `name:` used
 * by Claude Code as the skill identity. Emits the hyphen form (gsd-<cmd>)
 * so Claude Code autocomplete shows the canonical invocation form, not the
 * deprecated colon form. See #2808.
 *
 * Historical note: this previously returned `gsd:<cmd>` (colon) because
 * workflows called Skill(skill="gsd:<cmd>"). Those calls have been updated
 * to use hyphen form (#2808) so the colon rewrite is no longer needed.
 *
 * Codex must NOT use this helper: its adapter invokes skills as `$gsd-<cmd>`
 * (shell-var syntax) — hyphen form is already correct there.
 */
function skillFrontmatterName(skillDirName) {
  if (typeof skillDirName !== 'string') return skillDirName;
  // Return the hyphen form as-is (gsd-<cmd>) — canonical since #2808.
  return skillDirName;
}

/**
 * Qwen Code skills accept an optional numeric `priority` frontmatter field.
 * Per the Qwen skills spec (qwen-code/docs/users/features/skills.md, verified
 * #778): HIGHER values sort EARLIER in the `/skills` TUI listing (omitted ≈ 0;
 * negatives sort below unset). It affects ONLY the `/skills` list order —
 * slash-command completion and the `/help` view stay alphabetical.
 *
 * We assign descending priorities to GSD's main-loop commands so the most-used
 * workflow skills surface first; utility skills are deliberately left unset
 * (default 0) and sort below.
 *
 * NOTE: the #778 issue body proposed the INVERSE numbering (plan-phase: 10,
 * utilities: 90+). The verified spec shows that would BURY the core loop below
 * utilities, so we implement the spec-correct direction (core = high) instead.
 * Keyed by command stem (skill dir is `gsd-<stem>`).
 */
const QWEN_SKILL_PRIORITY = Object.freeze({
  'new-project': 100,
  'discuss-phase': 95,
  'plan-phase': 90,
  'execute-phase': 85,
  progress: 80,
  'verify-work': 75,
  phase: 70,
  review: 65,
  ship: 60,
  config: 55,
  surface: 50,
  'resume-work': 45,
  'pause-work': 40,
  help: 35,
  update: 30,
});

/**
 * Convert a Claude command (.md) to a Claude skill (SKILL.md).
 * Claude Code is the native format, so minimal conversion needed —
 * preserve allowed-tools as YAML multiline list, preserve argument-hint.
 * Emits `name: gsd-<cmd>` (hyphen) so Skill(skill="gsd-<cmd>") calls and
 * tab autocomplete use the canonical command namespace.
 */
function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, cmdNames = null) {
  const { frontmatter, body } = extractFrontmatterAndBody(content);
  if (!frontmatter) return content;

  // #3583: rewrite any /gsd:<cmd> or gsd:<cmd> in the body to the canonical
  // hyphen form (gsd-<cmd>) so installed SKILL.md bodies match the hyphen
  // `name:` Claude Code (and Qwen/Hermes) register under (#2808). `cmdNames`
  // is optional and pre-computed by the caller for performance; direct test
  // calls fall back to reading the list.
  const names = cmdNames || readGsdCommandNames();
  const normalizedBody = transformContentToHyphen(body, names);

  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const argumentHint = extractFrontmatterField(frontmatter, 'argument-hint');
  const agent = extractFrontmatterField(frontmatter, 'agent');
  // #769: preserve context: and effort: from source command files so they
  // are emitted into the installed SKILL.md frontmatter unchanged.
  const context = extractFrontmatterField(frontmatter, 'context');
  const effort = extractFrontmatterField(frontmatter, 'effort');

  // Preserve allowed-tools as YAML multiline list (Claude native format)
  const toolsMatch = frontmatter.match(/^allowed-tools:\s*\n((?:\s+-\s+.+\n?)*)/m);
  let toolsBlock = '';
  if (toolsMatch) {
    toolsBlock = 'allowed-tools:\n' + toolsMatch[1];
    // Ensure trailing newline
    if (!toolsBlock.endsWith('\n')) toolsBlock += '\n';
  }

  // Reconstruct frontmatter in Claude skill format
  const frontmatterName = skillFrontmatterName(skillName);
  let fm = `---\nname: ${frontmatterName}\ndescription: ${yamlQuote(description)}\n`;
  // Hermes' SKILL.md spec lists `version` as a required frontmatter field.
  // Track GSD's package version so Hermes' skill_view() reports a stable
  // identifier per install.
  if (runtime === 'hermes') fm += `version: ${yamlQuote(pkg.version)}\n`;
  // #778 (b) — Qwen-only numeric priority for /skills ordering. Scoped to qwen
  // so Claude/Hermes skill frontmatter is unchanged (they ignore the field, but
  // we keep their output byte-stable). skillName is the `gsd-<stem>` dir name.
  if (runtime === 'qwen') {
    const stem = typeof skillName === 'string' && skillName.startsWith('gsd-')
      ? skillName.slice(4)
      : skillName;
    const priority = Object.prototype.hasOwnProperty.call(QWEN_SKILL_PRIORITY, stem)
      ? QWEN_SKILL_PRIORITY[stem]
      : undefined;
    if (typeof priority === 'number') fm += `priority: ${priority}\n`;
  }
  if (argumentHint) fm += `argument-hint: ${yamlQuote(argumentHint)}\n`;
  if (agent) fm += `agent: ${agent}\n`;
  // #769: emit context: and effort: when present so the runtime can honour
  // them natively (context: fork = isolated subagent window; effort: =
  // token-budget tier). Fields are Claude-specific; unknown frontmatter
  // fields are silently ignored by other runtimes (backward-compatible).
  if (context) fm += `context: ${context}\n`;
  if (effort) fm += `effort: ${effort}\n`;
  if (toolsBlock) fm += toolsBlock;
  fm += '---';

  return `${fm}\n${normalizedBody}`;
}

function normalizeKimiSkillName(skillName) {
  let text = String(skillName || '').trim().toLowerCase();
  if (text.startsWith('/')) text = text.slice(1);
  if (text.startsWith('$')) text = text.slice(1);
  text = text.replace(/^gsd:/, 'gsd-');
  if (!text.startsWith('gsd-')) text = `gsd-${text}`;
  text = text.replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
  return text || 'gsd-command';
}

function convertGsdCommandReferencesToKimiSkillInvocations(content, cmdNames) {
  if (!Array.isArray(cmdNames) || cmdNames.length === 0) return content;
  const commands = [...cmdNames].sort((a, b) => b.length - a.length).map(escapeRegExp);
  const commandGroup = commands.join('|');
  const colonPattern = new RegExp(`(?<![A-Za-z0-9_/:.-])/?gsd:(${commandGroup})(?=[^A-Za-z0-9_-]|$)`, 'g');
  const hyphenPattern = new RegExp(`(?:/|\\$)gsd-(${commandGroup})(?=[^A-Za-z0-9_-]|$)`, 'g');

  return content
    .replace(colonPattern, (_, cmd) => `/skill:gsd-${cmd}`)
    .replace(hyphenPattern, (_, cmd) => `/skill:gsd-${cmd}`);
}

function convertClaudeCommandToKimiSkill(content, skillName, _runtime = null, cmdNames = null) {
  const { frontmatter, body } = extractFrontmatterAndBody(content);
  const kimiSkillName = normalizeKimiSkillName(skillName);
  const names = cmdNames || readGsdCommandNames();
  const description = frontmatter
    ? extractFrontmatterField(frontmatter, 'description') || `Run GSD workflow ${kimiSkillName}.`
    : `Run GSD workflow ${kimiSkillName}.`;
  const normalizedBody = convertGsdCommandReferencesToKimiSkillInvocations(
    frontmatter ? body : content,
    names
  );

  return `---\nname: ${kimiSkillName}\ndescription: ${yamlQuote(toSingleLine(description))}\n---\nInvoke this Kimi skill with \`/skill:${kimiSkillName}\`.\n\n${normalizedBody}`;
}

const KIMI_CANONICAL_GSD_AGENT_RE = /^gsd-[a-z0-9-]+$/;

function parseKimiAgentSource(source) {
  if (typeof source === 'string') {
    return {
      path: null,
      content: source,
    };
  }
  if (!source || typeof source !== 'object' || typeof source.content !== 'string') {
    return null;
  }
  return {
    path: typeof source.path === 'string' ? source.path : null,
    content: source.content,
  };
}

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;
}

function addKimiAgentDiagnostic(diagnostics, code, message, value, source = null) {
  diagnostics.push({
    level: 'warning',
    code,
    message,
    value,
    source,
  });
}

function mapKimiAgentContractTools(toolNames, diagnostics, sourceName) {
  const result = mapClaudeToolsToKimiTools(toolNames, { source: sourceName });
  diagnostics.push(...result.diagnostics);
  return result.tools;
}

function neutralizeKimiAgentPrompt(content) {
  const { frontmatter, body } = extractFrontmatterAndBody(content);
  let prompt = frontmatter ? body : content;
  prompt = neutralizeAgentReferences(prompt, 'AGENTS.md');
  prompt = prompt.replace(/~\/\.claude\/gsd-core\b/g, 'GSD core');
  prompt = prompt.replace(/\$HOME\/\.claude\/gsd-core\b/g, 'GSD core');
  return prompt.replace(/^\s*\r?\n/, '');
}

function pushKimiToolsYaml(lines, indent, tools) {
  const prefix = ' '.repeat(indent);
  if (!Array.isArray(tools) || tools.length === 0) {
    lines.push(`${prefix}tools: []`);
    return;
  }
  lines.push(`${prefix}tools:`);
  for (const tool of tools) {
    lines.push(`${prefix}  - ${yamlQuote(tool)}`);
  }
}

function buildKimiRootAgentYaml({ description, tools, subagents }) {
  const lines = [
    'version: 1',
    'agent:',
    '  name: gsd',
    `  description: ${yamlQuote(toSingleLine(description || 'Run GSD workflows in Kimi CLI.'))}`,
    '  extend: default',
    '  system_prompt_path: ./gsd.md',
  ];
  pushKimiToolsYaml(lines, 2, tools);

  if (subagents.length > 0) {
    lines.push('  subagents:');
    for (const subagent of subagents) {
      lines.push(`    ${subagent.name}:`);
      lines.push(`      path: ./subagents/${subagent.name}.yaml`);
      lines.push(`      description: ${yamlQuote(toSingleLine(subagent.description))}`);
    }
  }

  return `${lines.join('\n')}\n`;
}

function buildKimiSubagentYaml({ name, description, tools }) {
  const lines = [
    'version: 1',
    'agent:',
    `  name: ${name}`,
    `  description: ${yamlQuote(toSingleLine(description || `Run ${name}.`))}`,
    `  system_prompt_path: ./${name}.md`,
  ];
  pushKimiToolsYaml(lines, 2, tools);
  return `${lines.join('\n')}\n`;
}

function buildKimiAgentArtifacts({
  rootAgent = '',
  subagents = [],
  requestedSubagents = null,
} = {}) {
  const diagnostics = [];
  const rootSource = parseKimiAgentSource(rootAgent) || { path: null, content: '' };
  const { frontmatter: rootFrontmatter } = extractFrontmatterAndBody(rootSource.content);
  const rootDescription = rootFrontmatter
    ? extractFrontmatterField(rootFrontmatter, 'description') || 'Run GSD workflows in Kimi CLI.'
    : 'Run GSD workflows in Kimi CLI.';

  const subagentSources = Array.isArray(subagents) ? subagents : [];
  if (!Array.isArray(subagents)) {
    addKimiAgentDiagnostic(
      diagnostics,
      'kimi_unsupported_subagents_input',
      'Subagents input must be an array of Markdown strings or source objects.',
      typeof subagents,
      null
    );
  }

  const subagentMap = new Map();
  for (const source of subagentSources) {
    const parsed = parseKimiAgentSource(source);
    if (!parsed) {
      addKimiAgentDiagnostic(
        diagnostics,
        'kimi_unsupported_subagent_input',
        'Subagent source must be a Markdown string or an object with content.',
        typeof source,
        null
      );
      continue;
    }

    const { frontmatter } = extractFrontmatterAndBody(parsed.content);
    const fallbackName = parsed.path ? path.basename(parsed.path, path.extname(parsed.path)) : null;
    const name = frontmatter
      ? extractFrontmatterField(frontmatter, 'name') || fallbackName
      : fallbackName;
    if (!name || !KIMI_CANONICAL_GSD_AGENT_RE.test(name)) {
      addKimiAgentDiagnostic(
        diagnostics,
        'kimi_invalid_subagent_name',
        'Subagent source does not use a canonical gsd-* Kimi agent name.',
        name || '(missing)',
        parsed.path
      );
      continue;
    }

    const description = frontmatter
      ? extractFrontmatterField(frontmatter, 'description') || `Run ${name}.`
      : `Run ${name}.`;
    const tools = mapKimiAgentContractTools(parseFrontmatterTools(frontmatter), diagnostics, name);
    subagentMap.set(name, {
      name,
      description,
      tools,
      prompt: neutralizeKimiAgentPrompt(parsed.content),
    });
  }

  const requested = Array.isArray(requestedSubagents) && requestedSubagents.length > 0
    ? requestedSubagents
    : [...subagentMap.keys()];
  const selectedSubagents = [];
  for (const requestedName of requested) {
    if (subagentMap.has(requestedName)) {
      selectedSubagents.push(subagentMap.get(requestedName));
      continue;
    }
    addKimiAgentDiagnostic(
      diagnostics,
      'kimi_unknown_subagent',
      'Requested subagent was not generated and will not be emitted in Kimi YAML.',
      requestedName,
      null
    );
  }

  const rootTools = mapKimiAgentContractTools(parseFrontmatterTools(rootFrontmatter), diagnostics, 'gsd');
  if (selectedSubagents.length > 0 && !rootTools.includes('kimi_cli.tools.agent:Agent')) {
    rootTools.push('kimi_cli.tools.agent:Agent');
  }

  return {
    root: {
      name: 'gsd',
      yamlPath: 'agents/gsd.yaml',
      promptPath: 'agents/gsd.md',
      yaml: buildKimiRootAgentYaml({
        description: rootDescription,
        tools: rootTools,
        subagents: selectedSubagents,
      }),
      prompt: neutralizeKimiAgentPrompt(rootSource.content),
    },
    subagents: selectedSubagents.map((subagent) => ({
      name: subagent.name,
      yamlPath: `agents/subagents/${subagent.name}.yaml`,
      promptPath: `agents/subagents/${subagent.name}.md`,
      yaml: buildKimiSubagentYaml(subagent),
      prompt: subagent.prompt,
    })),
    diagnostics,
  };
}

/**
 * Convert a Claude agent (.md) to a Copilot agent (.agent.md).
 * Applies tool mapping + deduplication, formats tools as JSON array.
 * CONV-04: JSON array format. CONV-05: Tool name mapping.
 */
function convertClaudeAgentToCopilotAgent(content, isGlobal = false) {
  const converted = convertClaudeToCopilotContent(content, isGlobal);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const color = extractFrontmatterField(frontmatter, 'color');
  const toolsRaw = extractFrontmatterField(frontmatter, 'tools') || '';

  // CONV-04 + CONV-05: Map tools, deduplicate, format as JSON array
  const claudeTools = toolsRaw.split(',').map(t => t.trim()).filter(Boolean);
  const mappedTools = claudeTools.map(t => convertCopilotToolName(t));
  const uniqueTools = [...new Set(mappedTools)];
  const toolsArray = uniqueTools.length > 0
    ? "['" + uniqueTools.join("', '") + "']"
    : '[]';

  // Reconstruct frontmatter in Copilot format. Quote description (#2876)
  // so a leading YAML flow indicator (`[BETA] …`, `{ … }`, etc.) doesn't
  // crash the Copilot frontmatter loader.
  let fm = `---\nname: ${name}\ndescription: ${yamlQuote(description)}\ntools: ${toolsArray}\n`;
  if (color) fm += `color: ${color}\n`;
  fm += '---';

  return `${fm}\n${body}`;
}

/**
 * Apply Antigravity-specific content conversion — path replacement + command name conversion.
 * Path mappings depend on install mode:
 *   Global: ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agent/
 *   Local:  ~/.claude/ → .agent/, ./.claude/ → ./.agent/
 * Applied to ALL Antigravity content (skills, agents, engine files).
 * @param {string} content - Source content to convert
 * @param {boolean} [isGlobal=false] - Whether this is a global install
 */
function convertClaudeToAntigravityContent(content, isGlobal = false) {
  let c = content;
  if (isGlobal) {
    c = c.replace(/\$HOME\/\.claude\//g, '$HOME/.gemini/antigravity/');
    c = c.replace(/~\/\.claude\//g, '~/.gemini/antigravity/');
    // Bare form (no trailing slash) — must come after slash form to avoid double-replace
    c = c.replace(/\$HOME\/\.claude\b/g, '$HOME/.gemini/antigravity');
    c = c.replace(/~\/\.claude\b/g, '~/.gemini/antigravity');
  } else {
    c = c.replace(/\$HOME\/\.claude\//g, '.agent/');
    c = c.replace(/~\/\.claude\//g, '.agent/');
    // Bare form (no trailing slash) — must come after slash form to avoid double-replace
    c = c.replace(/\$HOME\/\.claude\b/g, '.agent');
    c = c.replace(/~\/\.claude\b/g, '.agent');
  }
  c = c.replace(/\.\/\.claude\//g, './.agent/');
  c = c.replace(/\.claude\//g, '.agent/');
  // Command name conversion (all gsd: references → gsd-)
  c = c.replace(/gsd:/g, 'gsd-');
  // Runtime-neutral agent name replacement (#766)
  c = neutralizeAgentReferences(c, 'GEMINI.md');
  return c;
}

/**
 * Convert a Claude command (.md) to an Antigravity skill (SKILL.md).
 * Transforms frontmatter to minimal name + description only.
 * Body passes through with path/command conversions applied.
 */
function convertClaudeCommandToAntigravitySkill(content, skillName, isGlobal = false) {
  const converted = convertClaudeToAntigravityContent(content, isGlobal);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = skillName || extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  // #2876: quote description so YAML flow indicators in the source
  // (e.g. `[BETA] …`) don't break downstream frontmatter parsers.
  const fm = `---\nname: ${name}\ndescription: ${yamlQuote(description)}\n---`;
  return `${fm}\n${body}`;
}

/**
 * Convert a Claude agent (.md) to an Antigravity agent.
 * Uses Gemini tool names since Antigravity runs on Gemini 3 backend.
 */
function convertClaudeAgentToAntigravityAgent(content, isGlobal = false) {
  const converted = convertClaudeToAntigravityContent(content, isGlobal);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const color = extractFrontmatterField(frontmatter, 'color');
  const toolsRaw = extractFrontmatterField(frontmatter, 'tools') || '';

  // Map tools to Gemini equivalents (reuse existing convertGeminiToolName)
  const claudeTools = toolsRaw.split(',').map(t => t.trim()).filter(Boolean);
  const mappedTools = claudeTools.map(t => convertGeminiToolName(t)).filter(Boolean);

  // #2876: quote description for the same reason as the skill variant.
  let fm = `---\nname: ${name}\ndescription: ${yamlQuote(description)}\ntools: ${mappedTools.join(', ')}\n`;
  if (color) fm += `color: ${color}\n`;
  fm += '---';

  return `${fm}\n${body}`;
}

function toSingleLine(value) {
  return value.replace(/\s+/g, ' ').trim();
}

function yamlQuote(value) {
  return JSON.stringify(value);
}

function yamlIdentifier(value) {
  const text = String(value).trim();
  if (/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(text)) {
    return text;
  }
  return yamlQuote(text);
}

function extractFrontmatterAndBody(content) {
  if (!content.startsWith('---')) {
    return { frontmatter: null, body: content };
  }

  const endIndex = content.indexOf('---', 3);
  if (endIndex === -1) {
    return { frontmatter: null, body: content };
  }

  return {
    frontmatter: content.substring(3, endIndex).trim(),
    body: content.substring(endIndex + 3),
  };
}

function extractFrontmatterField(frontmatter, fieldName) {
  const regex = new RegExp(`^${fieldName}:\\s*(.+)$`, 'm');
  const match = frontmatter.match(regex);
  if (!match) return null;
  return match[1].trim().replace(/^['"]|['"]$/g, '');
}

// Tool name mapping from Claude Code to Cursor CLI
const claudeToCursorTools = {
  Bash: 'Shell',
  Edit: 'StrReplace',
  AskUserQuestion: null, // No direct equivalent — use conversational prompting
  SlashCommand: null,    // No equivalent — skills are auto-discovered
};

/**
 * Convert a Claude Code tool name to Cursor CLI format
 * @returns {string|null} Cursor tool name, or null if tool should be excluded
 */
function convertCursorToolName(claudeTool) {
  if (claudeTool in claudeToCursorTools) {
    return claudeToCursorTools[claudeTool];
  }
  // MCP tools keep their format (Cursor supports MCP)
  if (claudeTool.startsWith('mcp__')) {
    return claudeTool;
  }
  // Most tools share the same name (Read, Write, Glob, Grep, Task, WebSearch, WebFetch, TodoWrite)
  return claudeTool;
}

function convertSlashCommandsToCursorSkillMentions(content) {
  // Keep leading "/" for slash commands; only normalize gsd: -> gsd-.
  // This preserves rendered "next step" commands like "/gsd-execute-phase 17".
  return content.replace(/gsd:/gi, 'gsd-');
}

function convertClaudeToCursorMarkdown(content) {
  let converted = convertSlashCommandsToCursorSkillMentions(content);
  // Replace tool name references in body text
  converted = converted.replace(/\bBash\(/g, 'Shell(');
  converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
  converted = converted.replace(/\bAskUserQuestion\b/g, 'conversational prompting');
  // Replace subagent_type from Claude to Cursor format
  converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  // Replace project-level Claude conventions with Cursor equivalents
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.cursor/rules/`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, '.cursor/rules/');
  converted = converted.replace(/`CLAUDE\.md`/g, '`.cursor/rules/`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, '.cursor/rules/');
  converted = converted.replace(/\.claude\/skills\//g, '.cursor/skills/');
  // Remove Claude Code-specific bug workarounds before brand replacement
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  // Replace "Claude Code" brand references with "Cursor"
  converted = converted.replace(/\bClaude Code\b/g, 'Cursor');
  return converted;
}

function getCursorSkillAdapterHeader(skillName) {
  return `<cursor_skill_adapter>
## A. Skill Invocation
- This skill is invoked when the user mentions \`${skillName}\` or describes a task matching this skill.
- Treat all user text after the skill mention as \`{{GSD_ARGS}}\`.
- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.

## B. User Prompting
When the workflow needs user input, prompt the user conversationally:
- Present options as a numbered list in your response text
- Ask the user to reply with their choice
- For multi-select, ask for comma-separated numbers

## C. Tool Usage
Use these Cursor tools when executing GSD workflows:
- \`Shell\` for running commands (terminal operations)
- \`StrReplace\` for editing existing files
- \`Read\`, \`Write\`, \`Glob\`, \`Grep\`, \`Task\`, \`WebSearch\`, \`WebFetch\`, \`TodoWrite\` as needed

## D. Subagent Spawning
When the workflow needs to spawn a subagent:
- Use \`Task(subagent_type="generalPurpose", ...)\`
- The \`model\` parameter maps to Cursor's model options (e.g., "fast")
</cursor_skill_adapter>`;
}

function convertClaudeCommandToCursorSkill(content, skillName) {
  const converted = convertClaudeToCursorMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  const adapter = getCursorSkillAdapterHeader(skillName);

  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
}

/**
 * Convert a Claude Code command to a Cursor 1.6 slash command (#785).
 *
 * Cursor slash commands live in `.cursor/commands/<name>.md` and are
 * plain markdown — no YAML frontmatter, no adapter header. The filename
 * becomes the command name (e.g. `gsd-help.md` → `/gsd-help`).
 *
 * Applies the same `convertClaudeToCursorMarkdown` transforms as the skill
 * converter (tool renames, brand substitution, slash-command normalisation),
 * then strips the YAML frontmatter block so only the prose body remains.
 *
 * @param {string} content   raw Claude Code command markdown (may have frontmatter)
 * @param {string} _commandName  the target command name (unused; present for
 *   API symmetry with other converters so the runtime-artifact-layout stage
 *   function can call it uniformly)
 * @returns {string} plain markdown body, no frontmatter
 */
function convertClaudeCommandToCursorCommand(content, _commandName) {
  const converted = convertClaudeToCursorMarkdown(content);
  const { body } = extractFrontmatterAndBody(converted);
  return body.trimStart();
}

/**
 * Convert Claude Code agent markdown to Cursor agent format.
 * Strips frontmatter fields Cursor doesn't support (color, skills),
 * converts tool references, and adds a role context header.
 */
function convertClaudeAgentToCursorAgent(content) {
  let converted = convertClaudeToCursorMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n${body}`;
}

// --- Windsurf converters ---
// Windsurf uses a tool set similar to Cursor.
// Config lives in .windsurf/ (local) and ~/.codeium/windsurf/ (global).

// Tool name mapping from Claude Code to Windsurf Cascade
const claudeToWindsurfTools = {
  Bash: 'Shell',
  Edit: 'StrReplace',
  AskUserQuestion: null, // No direct equivalent — use conversational prompting
  SlashCommand: null,    // No equivalent — skills are auto-discovered
};

/**
 * Convert a Claude Code tool name to Windsurf Cascade format
 * @returns {string|null} Windsurf tool name, or null if tool should be excluded
 */
function convertWindsurfToolName(claudeTool) {
  if (claudeTool in claudeToWindsurfTools) {
    return claudeToWindsurfTools[claudeTool];
  }
  // MCP tools keep their format (Windsurf supports MCP)
  if (claudeTool.startsWith('mcp__')) {
    return claudeTool;
  }
  // Most tools share the same name (Read, Write, Glob, Grep, Task, WebSearch, WebFetch, TodoWrite)
  return claudeTool;
}

function convertSlashCommandsToWindsurfSkillMentions(content) {
  // Keep leading "/" for slash commands; only normalize gsd: -> gsd-.
  return content.replace(/gsd:/gi, 'gsd-');
}

function convertClaudeToWindsurfMarkdown(content) {
  let converted = convertSlashCommandsToWindsurfSkillMentions(content);
  // Replace tool name references in body text
  converted = converted.replace(/\bBash\(/g, 'Shell(');
  converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
  converted = converted.replace(/\bAskUserQuestion\b/g, 'conversational prompting');
  // Replace subagent_type from Claude to Windsurf format
  converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  // Replace project-level Claude conventions with Windsurf equivalents
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.windsurf/rules`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, '.windsurf/rules');
  converted = converted.replace(/`CLAUDE\.md`/g, '`.windsurf/rules`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, '.windsurf/rules');
  converted = converted.replace(/\.claude\/skills\//g, '.windsurf/skills/');
  // Remove Claude Code-specific bug workarounds before brand replacement
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  // Replace "Claude Code" brand references with "Windsurf"
  converted = converted.replace(/\bClaude Code\b/g, 'Windsurf');
  return converted;
}

function getWindsurfSkillAdapterHeader(skillName) {
  return `<windsurf_skill_adapter>
## A. Skill Invocation
- This skill is invoked when the user mentions \`${skillName}\` or describes a task matching this skill.
- Treat all user text after the skill mention as \`{{GSD_ARGS}}\`.
- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.

## B. User Prompting
When the workflow needs user input, prompt the user conversationally:
- Present options as a numbered list in your response text
- Ask the user to reply with their choice
- For multi-select, ask for comma-separated numbers

## C. Tool Usage
Use these Windsurf tools when executing GSD workflows:
- \`Shell\` for running commands (terminal operations)
- \`StrReplace\` for editing existing files
- \`Read\`, \`Write\`, \`Glob\`, \`Grep\`, \`Task\`, \`WebSearch\`, \`WebFetch\`, \`TodoWrite\` as needed

## D. Subagent Spawning
When the workflow needs to spawn a subagent:
- Use \`Task(subagent_type="generalPurpose", ...)\`
- The \`model\` parameter maps to Windsurf's model options (e.g., "fast")
</windsurf_skill_adapter>`;
}

function convertClaudeCommandToWindsurfSkill(content, skillName) {
  const converted = convertClaudeToWindsurfMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  const adapter = getWindsurfSkillAdapterHeader(skillName);

  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
}

/**
 * Convert Claude Code agent markdown to Windsurf agent format.
 * Strips frontmatter fields Windsurf doesn't support (color, skills),
 * converts tool references, and adds a role context header.
 */
function convertClaudeAgentToWindsurfAgent(content) {
  let converted = convertClaudeToWindsurfMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n${body}`;
}

// --- Augment converters ---
// Augment uses a tool set similar to Cursor/Windsurf.
// Config lives in .augment/ (local) and ~/.augment/ (global).

const claudeToAugmentTools = {
  Bash: 'launch-process',
  Edit: 'str-replace-editor',
  AskUserQuestion: null,
  SlashCommand: null,
  TodoWrite: 'add_tasks',
};

function convertAugmentToolName(claudeTool) {
  if (claudeTool in claudeToAugmentTools) {
    return claudeToAugmentTools[claudeTool];
  }
  if (claudeTool.startsWith('mcp__')) {
    return claudeTool;
  }
  const toolMapping = {
    Read: 'view',
    Write: 'save-file',
    Glob: 'view',
    Grep: 'grep',
    Task: null,
    WebSearch: 'web-search',
    WebFetch: 'web-fetch',
  };
  return toolMapping[claudeTool] || claudeTool;
}

function convertSlashCommandsToAugmentSkillMentions(content) {
  return content.replace(/gsd:/gi, 'gsd-');
}

function convertClaudeToAugmentMarkdown(content) {
  let converted = convertSlashCommandsToAugmentSkillMentions(content);
  converted = converted.replace(/\bBash\(/g, 'launch-process(');
  converted = converted.replace(/\bEdit\(/g, 'str-replace-editor(');
  converted = converted.replace(/\bRead\(/g, 'view(');
  converted = converted.replace(/\bWrite\(/g, 'save-file(');
  converted = converted.replace(/\bTodoWrite\(/g, 'add_tasks(');
  converted = converted.replace(/\bAskUserQuestion\b/g, 'conversational prompting');
  // Replace subagent_type from Claude to Augment format
  converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  // Replace project-level Claude conventions with Augment equivalents
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.augment/rules/`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, '.augment/rules/');
  converted = converted.replace(/`CLAUDE\.md`/g, '`.augment/rules/`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, '.augment/rules/');
  converted = converted.replace(/\.claude\/skills\//g, '.augment/skills/');
  // Remove Claude Code-specific bug workarounds before brand replacement
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  // Replace "Claude Code" brand references with "Augment"
  converted = converted.replace(/\bClaude Code\b/g, 'Augment');
  return converted;
}

function getAugmentSkillAdapterHeader(skillName) {
  return `<augment_skill_adapter>
## A. Skill Invocation
- This skill is invoked when the user mentions \`${skillName}\` or describes a task matching this skill.
- Treat all user text after the skill mention as \`{{GSD_ARGS}}\`.
- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.

## B. User Prompting
When the workflow needs user input, prompt the user conversationally:
- Present options as a numbered list in your response text
- Ask the user to reply with their choice
- For multi-select, ask for comma-separated numbers

## C. Tool Usage
Use these Augment tools when executing GSD workflows:
- \`launch-process\` for running commands (terminal operations)
- \`str-replace-editor\` for editing existing files
- \`view\` for reading files and listing directories
- \`save-file\` for creating new files
- \`grep\` for searching code (or use MCP servers for advanced search)
- \`web-search\`, \`web-fetch\` for web queries
- \`add_tasks\`, \`view_tasklist\`, \`update_tasks\` for task management

## D. Subagent Spawning
When the workflow needs to spawn a subagent:
- Use the built-in subagent spawning capability
- Define agent prompts in \`.augment/agents/\` directory
</augment_skill_adapter>`;
}

function convertClaudeCommandToAugmentSkill(content, skillName) {
  const converted = convertClaudeToAugmentMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  const adapter = getAugmentSkillAdapterHeader(skillName);

  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
}

/**
 * Convert Claude Code agent markdown to Augment agent format.
 * Strips frontmatter fields Augment doesn't support (color, skills),
 * converts tool references, and cleans up for Augment agents.
 */
function convertClaudeAgentToAugmentAgent(content) {
  let converted = convertClaudeToAugmentMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n${body}`;
}

/**
 * Copy Claude commands as Augment skills — one folder per skill with SKILL.md.
 * Mirrors copyCommandsAsCursorSkills but uses Augment converters.
 */

function convertSlashCommandsToTraeSkillMentions(content) {
  return content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
    return `/gsd-${commandName}`;
  });
}

function convertClaudeToTraeMarkdown(content) {
  let converted = convertSlashCommandsToTraeSkillMentions(content);
  converted = converted.replace(/\bBash\(/g, 'Shell(');
  converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
  // Replace general-purpose subagent type with Trae's equivalent "general_purpose_task"
  converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="general_purpose_task"');
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.trae/rules/`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, '.trae/rules/');
  converted = converted.replace(/`CLAUDE\.md`/g, '`.trae/rules/`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, '.trae/rules/');
  converted = converted.replace(/\.claude\/skills\//g, '.trae/skills/');
  converted = converted.replace(/\.\/\.claude\//g, './.trae/');
  converted = converted.replace(/\.claude\//g, '.trae/');
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  converted = converted.replace(/\bClaude Code\b/g, 'Trae');
  return converted;
}

function convertClaudeCommandToTraeSkill(content, skillName) {
  const converted = convertClaudeToTraeMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  // #2876: quote so YAML flow indicators (`[BETA] …`) don't break Trae's
  // frontmatter parser.
  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n${body}`;
}

function convertClaudeAgentToTraeAgent(content) {
  let converted = convertClaudeToTraeMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n${body}`;
}

function convertSlashCommandsToCodebuddySkillMentions(content) {
  return content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
    return `/gsd-${commandName}`;
  });
}

function convertClaudeToCodebuddyMarkdown(content) {
  let converted = convertSlashCommandsToCodebuddySkillMentions(content);
  // CodeBuddy uses the same tool names as Claude Code (Bash, Edit, Read, Write, etc.)
  // No tool name conversion needed
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`CODEBUDDY.md`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, 'CODEBUDDY.md');
  converted = converted.replace(/`CLAUDE\.md`/g, '`CODEBUDDY.md`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, 'CODEBUDDY.md');
  converted = converted.replace(/\.claude\/skills\//g, '.codebuddy/skills/');
  converted = converted.replace(/\.\/\.claude\//g, './.codebuddy/');
  converted = converted.replace(/\.claude\//g, '.codebuddy/');
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  converted = converted.replace(/\bClaude Code\b/g, 'CodeBuddy');
  return converted;
}

function convertClaudeCommandToCodebuddySkill(content, skillName) {
  const converted = convertClaudeToCodebuddyMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  // #2876: quote so YAML flow indicators (`[BETA] …`) don't break
  // CodeBuddy's frontmatter parser.
  //
  // #789: mark user-invocable:false so the skill is NOT shown in CodeBuddy's
  // '/' menu (it defaults to true). The commands/ surface (#789) is the sole
  // '/' entry point; skills remain model-invocable background knowledge,
  // avoiding a duplicated /gsd-* entry per workflow.
  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\nuser-invocable: false\n---\n${body}`;
}

/**
 * Convert a Claude Code slash-command (.md) to a CodeBuddy slash-command (.md).
 *
 * CodeBuddy reads user-level slash commands from ~/.codebuddy/commands/<name>.md
 * (https://www.codebuddy.ai/docs/cli/slash-commands). The filename determines the
 * command name (gsd-help.md → /gsd-help), so the Claude-specific `name: gsd:<x>`
 * frontmatter field is dropped. CodeBuddy command frontmatter supports
 * `description` and `argument-hint`; both are preserved when present. The body is
 * brand/path-converted via convertClaudeToCodebuddyMarkdown.
 *
 * @param {string} content      raw Claude command markdown
 * @param {string} commandName  installed command name (e.g. 'gsd-help')
 * @returns {string}
 */
function convertClaudeCommandToCodebuddyCommand(content, commandName) {
  const converted = convertClaudeToCodebuddyMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${commandName}.`;
  let argumentHint = '';
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) description = maybeDescription;
    const maybeArgHint = extractFrontmatterField(frontmatter, 'argument-hint');
    if (maybeArgHint) argumentHint = maybeArgHint;
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  // #2876: quote values so YAML flow indicators (`[BETA] …`, `[name]`) don't
  // break CodeBuddy's frontmatter parser.
  const lines = ['---', `description: ${yamlQuote(shortDescription)}`];
  if (argumentHint) lines.push(`argument-hint: ${yamlQuote(toSingleLine(argumentHint))}`);
  lines.push('---', body.trimStart());
  return lines.join('\n');
}

function convertClaudeAgentToCodebuddyAgent(content) {
  let converted = convertClaudeToCodebuddyMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';

  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n${body}`;
}

// ── Cline converters ────────────────────────────────────────────────────────

function convertClaudeToCliineMarkdown(content) {
  let converted = content;
  // Cline uses the same tool names as Claude Code — no tool name conversion needed
  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.clinerules`');
  converted = converted.replace(/\.\/CLAUDE\.md/g, '.clinerules');
  converted = converted.replace(/`CLAUDE\.md`/g, '`.clinerules`');
  converted = converted.replace(/\bCLAUDE\.md\b/g, '.clinerules');
  // Slash forms first (most specific — superset of bare forms)
  converted = converted.replace(/\.claude\/skills\//g, '.cline/skills/');
  converted = converted.replace(/\.\/\.claude\//g, './.cline/');
  converted = converted.replace(/\.claude\//g, '.cline/');
  // Bare forms (no trailing slash) — after slash forms to avoid double-rewrite
  converted = converted.replace(/~\/\.claude\b/g, '~/.cline');
  converted = converted.replace(/\$HOME\/\.claude\b/g, '$HOME/.cline');
  // Environment variable name rewrite
  converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'CLINE_CONFIG_DIR');
  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
  converted = converted.replace(/\bClaude Code\b/g, 'Cline');
  return converted;
}

function convertClaudeAgentToClineAgent(content) {
  let converted = convertClaudeToCliineMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;
  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
  return `${cleanFrontmatter}\n${body}`;
}

/**
 * Convert a Claude command (.md) to a Cline skill (SKILL.md).
 * Emits ONLY name + description frontmatter per the Cline skills spec
 * (https://docs.cline.bot/customization/skills) — no allowed-tools,
 * argument-hint, agent, or other Claude-specific fields.
 * Body is hyphen-normalised then converted via convertClaudeToCliineMarkdown
 * (.claude/→.cline/, "Claude Code"→"Cline", etc.).
 * Cline uses Claude-Code-compatible tool names, so no adapter header is needed.
 * Targets ~/.cline/skills/<name>/SKILL.md for Cline >= v3.48.0.
 */
function convertClaudeCommandToClineSkill(content, skillName, runtime = null, cmdNames = null) {
  const { frontmatter, body } = extractFrontmatterAndBody(content);
  if (!frontmatter) return content;

  // Hyphen-normalise /gsd:<cmd> → gsd-<cmd> references in the body, then
  // apply Cline-specific markdown rewrites (.claude/→.cline/, etc.).
  const names = cmdNames || readGsdCommandNames();
  const normalizedBody = transformContentToHyphen(body, names);
  const clineBody = convertClaudeToCliineMarkdown(normalizedBody);

  // Extract description; fall back to a generic string if absent.
  let description = extractFrontmatterField(frontmatter, 'description');
  if (!description) description = `Run GSD workflow ${skillName}.`;
  description = toSingleLine(description);
  // Cline documented max is 1024 code points (not UTF-16 code units).
  // Use Array.from to iterate by code point so that multibyte characters
  // (e.g. emoji, astral-plane chars) are never split, which would produce
  // lone surrogates and corrupt the YAML output.
  const cp = Array.from(description);
  const shortDescription = cp.length > 1024
    ? cp.slice(0, 1021).join('') + '...'
    : description;

  const fm = `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---`;
  return `${fm}\n${clineBody}`;
}

// ── End Cline converters ─────────────────────────────────────────────────────

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) => {
    return `$gsd-${String(commandName).toLowerCase()}`;
  });
  // Convert hyphen-style command references (workflow output) to Codex $ prefix.
  // A real /gsd-<cmd> MENTION is defined positively by two boundaries, so any
  // in-path occurrence is excluded by construction (no denylist of preceding
  // chars to maintain — see #712, supersedes the #637/#704 lookbehind treadmill):
  //   1. Left boundary: opens at start-of-string, whitespace, or an inline-prose
  //      delimiter (backtick/quote/paren/bracket) — e.g. `/gsd-execute-phase`.
  //   2. Right boundary: the command token is NOT followed by a path separator
  //      `/` (a path continues: `/gsd-core/bin/...`; a command does not). The
  //      `(?![a-z0-9/-])` also blocks regex backtracking to a shorter command.
  // This converts backtick-wrapped MENTIONS (`/gsd-foo`) while leaving backtick-
  // wrapped PATHS (`/gsd-core/workflows/update.md`) untouched (#712).
  converted = converted.replace(/(?<=^|[\s`"'([])\/gsd-([a-z0-9-]+)(?![a-z0-9/-])/gi, (_, commandName) => {
    return `$gsd-${String(commandName).toLowerCase()}`;
  });
  return converted;
}

function convertClaudeToCodexMarkdown(content) {
  let converted = convertSlashCommandsToCodexSkillMentions(content);
  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
  // Remove /clear references — Codex has no equivalent command
  // Handle backtick-wrapped: `\/clear` then: → (removed)
  converted = converted.replace(/`\/clear`\s*,?\s*then:?\s*\n?/gi, '');
  // Handle bare: /clear then: → (removed)
  converted = converted.replace(/\/clear\s*,?\s*then:?\s*\n?/gi, '');
  // Handle standalone /clear on its own line
  converted = converted.replace(/^\s*`?\/clear`?\s*$/gm, '');
  // Path replacement: .claude → .codex (#1430)
  converted = converted.replace(/\$HOME\/\.claude\//g, '$HOME/.codex/');
  converted = converted.replace(/~\/\.claude\//g, '~/.codex/');
  converted = converted.replace(/\.\/\.claude\//g, './.codex/');
  // Bare ~/.claude without trailing slash (e.g. configDir = ~/.claude)
  converted = converted.replace(/\$HOME\/\.claude\b/g, '$HOME/.codex');
  converted = converted.replace(/~\/\.claude\b/g, '~/.codex');
  // Bare/project-relative .claude/... references (#2639). Covers strings like
  // "check `.claude/skills/`" where there is no ~/, $HOME/, or ./ anchor.
  // Negative lookbehind prevents double-replacing already-anchored forms and
  // avoids matching inside URLs or other slash-prefixed paths.
  converted = converted.replace(/(?<![A-Za-z0-9_\-./~$])\.claude\//g, '.codex/');
  // `.claudeignore` → `.codexignore` (#2639). Codex honors its own ignore
  // file; leaving the Claude-specific name is misleading in agent prompts.
  converted = converted.replace(/\.claudeignore\b/g, '.codexignore');
  // Runtime-neutral agent name replacement (#766)
  converted = neutralizeAgentReferences(converted, 'AGENTS.md');
  return converted;
}

function getCodexSkillAdapterHeader(skillName) {
  const invocation = `$${skillName}`;
  return `<codex_skill_adapter>
## A. Skill Invocation
- This skill is invoked by mentioning \`${invocation}\`.
- Treat all user text after \`${invocation}\` as \`{{GSD_ARGS}}\`.
- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.

## B. AskUserQuestion → request_user_input Mapping
GSD workflows use \`AskUserQuestion\` (Claude Code syntax). Translate to Codex \`request_user_input\`:

Parameter mapping:
- \`header\` → \`header\`
- \`question\` → \`question\`
- Options formatted as \`"Label" — description\` → \`{label: "Label", description: "description"}\`
- Generate \`id\` from header: lowercase, replace spaces with underscores

Batched calls:
- \`AskUserQuestion([q1, q2])\` → single \`request_user_input\` with multiple entries in \`questions[]\`

Multi-select workaround:
- Codex has no \`multiSelect\`. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.

Execute mode fallback:
- When \`request_user_input\` is rejected or unavailable, activate TEXT_MODE: append \`--text\` to \`{{GSD_ARGS}}\` so the workflow's built-in text-mode branching takes over. Present every \`AskUserQuestion\` call as a plain-text numbered list, then stop and wait for the user's reply. Do NOT pick a default and continue (#3018 / #3808).
- You may only proceed without a user answer when one of these is true:
  (a) the invocation included an explicit non-interactive flag (\`--auto\` or \`--all\`),
  (b) the user has explicitly approved a specific default for this question, or
  (c) the workflow's documented contract says defaults are safe (e.g. autonomous lifecycle paths).
- Do NOT write workflow artifacts (CONTEXT.md, DISCUSSION-LOG.md, PLAN.md, checkpoint files) until the user has answered the plain-text questions or one of (a)-(c) above applies. Surfacing the questions and waiting is the correct response — silently defaulting and writing artifacts is the #3018 failure mode.

## C. Task() → spawn_agent Mapping
GSD workflows use \`Task(...)\` (Claude Code syntax). Translate to Codex collaboration tools:

Direct mapping:
- \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
- \`Agent(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
- \`Task(model="...")\` → omit. \`spawn_agent\` has no inline \`model\` parameter;
  GSD embeds the resolved per-agent model directly into each agent's \`.toml\`
  at install time so \`model_overrides\` from \`.planning/config.json\` and
  \`~/.gsd/defaults.json\` are honored automatically by Codex's agent router.
- Resolved \`reasoning_effort="low|medium|high|xhigh"\` (\`xhigh\` is a GSD/Codex tier, not a generic runtime enum) → pass \`reasoning_effort\`
  to \`spawn_agent\` when the runtime/tool supports it. Omit missing, empty,
  inherited, or unsupported values; do not invent one-off effort literals in
  workflow prose.
- \`fork_context: false\` by default — GSD agents load their own context via \`<files_to_read>\` blocks
- \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct Codex mapping.
  Codex \`spawn_agent\` does not create or bind a git worktree automatically.
  Workflows that require this isolation must fail closed or use an explicit
  manual worktree protocol before spawning (#3360).

Spawn restriction:
- Codex restricts \`spawn_agent\` to cases where the user has explicitly
  requested sub-agents. When automatic spawning is not permitted, do the
  work inline in the current agent rather than attempting to force a spawn.
- In some Codex sessions, multi-agent tooling can be deferred. If \`spawn_agent\`
  is not currently visible, discover tools first via \`tool_search\` before
  defaulting to inline execution.

Parallel fan-out:
- Spawn multiple agents → collect agent IDs → \`wait(ids)\` for all to complete

Result parsing:
- Look for structured markers in agent output: \`CHECKPOINT\`, \`PLAN COMPLETE\`, \`SUMMARY\`, etc.
- \`close_agent(id)\` after collecting results from each agent
</codex_skill_adapter>`;
}

function convertClaudeCommandToCodexSkill(content, skillName) {
  const converted = convertClaudeToCodexMarkdown(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
  const adapter = getCodexSkillAdapterHeader(skillName);

  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
}

/**
 * Convert Claude Code agent markdown to Codex agent format.
 * Applies base markdown conversions, then adds a <codex_agent_role> header
 * and cleans up frontmatter (removes tools/color fields).
 */
function convertClaudeAgentToCodexAgent(content) {
  let converted = convertClaudeToCodexMarkdown(content);

  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  if (!frontmatter) return converted;

  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
  const description = extractFrontmatterField(frontmatter, 'description') || '';
  const tools = extractFrontmatterField(frontmatter, 'tools') || '';

  const roleHeader = `<codex_agent_role>
role: ${name}
tools: ${tools}
purpose: ${toSingleLine(description)}
</codex_agent_role>`;

  const cleanFrontmatter = `---\nname: ${yamlQuote(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;

  return `${cleanFrontmatter}\n\n${roleHeader}\n${body}`;
}

/**
 * Generate a per-agent .toml config file for Codex.
 * Sets required agent metadata, sandbox_mode, and developer_instructions
 * from the agent markdown content.
 *
 * @param {string} agentName
 * @param {string} agentContent
 * @param {object|null} modelOverrides
 * @param {object|null} runtimeResolver  — runtime-aware tier resolver from readGsdRuntimeProfileResolver
 * @param {object|null} effortCfg        — #443: merged effort config from readGsdEffectiveEffortConfig
 */
function generateCodexAgentToml(agentName, agentContent, modelOverrides = null, runtimeResolver = null, effortCfg = null) {
  const sandboxMode = CODEX_AGENT_SANDBOX[agentName] || 'read-only';
  const { frontmatter, body } = extractFrontmatterAndBody(agentContent);
  const frontmatterText = frontmatter || '';
  const resolvedName = extractFrontmatterField(frontmatterText, 'name') || agentName;
  const resolvedDescription = toSingleLine(
    extractFrontmatterField(frontmatterText, 'description') || `GSD agent ${resolvedName}`
  );
  const instructions = body.trim();

  const lines = [
    `name = ${JSON.stringify(resolvedName)}`,
    `description = ${JSON.stringify(resolvedDescription)}`,
    `sandbox_mode = "${sandboxMode}"`,
  ];

  // Embed model override when configured in ~/.gsd/defaults.json so that
  // model_overrides is respected on Codex (which uses static TOML, not inline
  // Task() model parameters). See #2256.
  // Precedence: per-agent model_overrides > runtime-aware tier resolution (#2517).
  const modelOverride = modelOverrides?.[resolvedName] || modelOverrides?.[agentName];
  if (modelOverride) {
    lines.push(`model = ${JSON.stringify(modelOverride)}`);
  } else if (runtimeResolver) {
    // #2517 — runtime-aware tier resolution. Embeds Codex-native model + reasoning_effort
    // from RUNTIME_PROFILE_MAP / model_profile_overrides for the configured tier.
    const entry = runtimeResolver.resolve(resolvedName) || runtimeResolver.resolve(agentName);
    if (entry?.model) {
      lines.push(`model = ${JSON.stringify(entry.model)}`);
      // model is resolved here; reasoning_effort from catalog tier is REPLACED by the
      // unified effort resolver below (#443). Do NOT emit entry.reasoning_effort here.
    }
  }

  // #443 — Unified effort for Codex .toml. Uses the same config-driven precedence chain
  // as the Claude .md effort injection (resolveInstallTimeEffort), so both runtimes read
  // from the same effort.agent_overrides / effort.routing_tier_defaults / effort.default
  // config source. Codex does not support 'max' → clamped to 'xhigh' by
  // gsdRenderEffortForRuntime('codex', ...).
  const _universalEffortCodex = resolveInstallTimeEffort(effortCfg, resolvedName !== agentName ? resolvedName : agentName);
  const _renderedEffortCodex = _getGsdEffortCatalog().renderEffortForRuntime('codex', _universalEffortCodex).value;
  lines.push(`model_reasoning_effort = ${JSON.stringify(_renderedEffortCodex)}`);

  // #774 — Emit service_tier and model_verbosity for light-tier agents.
  // Light-tier agents (routingTier: "light" in model-catalog.json) are haiku-equivalent
  // and benefit from Codex's "flex" service tier (lower cost, background processing)
  // and "low" verbosity (reduced token output). Both fields are validated against the
  // Codex ConfigProfile schema (codex-rs/config/src/profile_toml.rs):
  //   service_tier: Option<String>  — "flex" | "fast" (legacy)
  //   model_verbosity: Option<Verbosity> — "low" | "medium" | "high"
  const { AGENT_DEFAULT_TIERS: _agentTiers } = _getGsdEffortCatalog();
  const _agentRoutingTier = _agentTiers?.[resolvedName] || _agentTiers?.[agentName];
  if (_agentRoutingTier === 'light') {
    lines.push(`service_tier = "flex"`);
    lines.push(`model_verbosity = "low"`);
  }

  // Agent prompts contain raw backslashes in regexes and shell snippets.
  // TOML literal multiline strings preserve them without escape parsing.
  lines.push(`developer_instructions = '''`);
  lines.push(instructions);
  lines.push(`'''`);

  return lines.join('\n') + '\n';
}

/**
 * Generate the agents/openai.yaml TUI chip metadata content for a Codex skill.
 *
 * This file is written alongside SKILL.md as <skill-dir>/agents/openai.yaml.
 * Codex loads it as a SkillMetadataFile (codex-rs/core-skills/src/loader.rs),
 * making the skill discoverable in the /skills TUI popup with a display name
 * and short description. If the file is absent, Codex silently skips it (fails open).
 *
 * Schema (interface section):
 *   display_name: short human-readable skill name (strip gsd- prefix)
 *   short_description: 1-2 sentence description for TUI chip, ≤180 chars
 *
 * @param {string} skillName - Full skill name e.g. "gsd-plan-phase"
 * @param {string} shortDescription - Description text (already truncated by caller)
 * @returns {string} YAML content for agents/openai.yaml
 */
function generateCodexSkillMetadataYaml(skillName, shortDescription) {
  // Display name: strip "gsd-" prefix and convert hyphens to spaces for readability.
  const displayName = skillName.replace(/^gsd-/, '').replace(/-/g, ' ');
  // yamlQuote (= JSON.stringify) handles all YAML-unsafe chars: backslashes,
  // quotes, newlines, control characters, and Unicode escapes.
  return [
    'interface:',
    `  display_name: ${yamlQuote(displayName)}`,
    `  short_description: ${yamlQuote(shortDescription)}`,
    '',
  ].join('\n');
}

/**
 * Write agents/openai.yaml TUI chip metadata for each gsd-* skill directory.
 *
 * Called after layout-driven skill install for Codex. Iterates every gsd-*
 * skill directory in skillsDir, reads the SKILL.md frontmatter to extract the
 * short-description already emitted by convertClaudeCommandToCodexSkill, then
 * writes <skill-dir>/agents/openai.yaml using generateCodexSkillMetadataYaml.
 *
 * Fails open: individual skill directories that cannot be processed are silently
 * skipped so a single malformed SKILL.md cannot block the whole install.
 *
 * User-owned skill directories (e.g. gsd-dev-preferences) are explicitly
 * skipped so existing user-authored agents/openai.yaml files are never
 * overwritten. These dirs are listed in the same USER_OWNED_SKILL_DIRS
 * constant used by installOpencodeFamilySkills.
 *
 * The YAML-quoted description value is unescaped before embedding so that
 * YAML escape sequences (e.g. \" in a double-quoted scalar) become the
 * literal characters they represent rather than being double-escaped in the
 * output.
 *
 * @param {string} skillsDir - Path to the skills/ directory (e.g. ~/.codex/skills)
 */
function writeCodexSkillMetadataFiles(skillsDir) {
  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 overwritten by GSD's install path.
  const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
  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
    const skillDir = path.join(skillsDir, entry.name);
    const skillMdPath = path.join(skillDir, 'SKILL.md');
    try {
      const content = fs.readFileSync(skillMdPath, 'utf8');
      const { frontmatter } = extractFrontmatterAndBody(content);
      // Prefer the short-description field emitted by convertClaudeCommandToCodexSkill;
      // fall back to description, then a synthetic label from the skill name.
      let shortDesc = '';
      if (frontmatter) {
        // SKILL.md uses YAML frontmatter with a nested metadata.short-description key.
        // extractFrontmatterField handles only top-level keys; parse the metadata block
        // by looking for "  short-description:" directly.
        const metaMatch = frontmatter.match(/^[ \t]*metadata\s*:\s*\n((?:[ \t]+.*\n?)*)/m);
        if (metaMatch) {
          const metaBlock = metaMatch[1];
          const sdMatch = metaBlock.match(/^[ \t]+short-description\s*:\s*(.+)$/m);
          if (sdMatch) {
            // Unescape YAML double-quoted scalar escapes before embedding.
            // convertClaudeCommandToCodexSkill always emits a double-quoted
            // value (via yamlQuote) so only double-quote unescaping is needed.
            let raw = sdMatch[1].trim();
            if (raw.startsWith('"') && raw.endsWith('"')) {
              // Strip outer double-quotes and decode \" → " and \\ → \
              raw = raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
            } else {
              // Single-quoted or unquoted: strip surrounding quotes/whitespace
              raw = raw.replace(/^["']|["']$/g, '');
            }
            shortDesc = raw;
          }
        }
        if (!shortDesc) {
          shortDesc = extractFrontmatterField(frontmatter, 'description') || '';
        }
      }
      if (!shortDesc) {
        shortDesc = `Run GSD workflow ${entry.name}.`;
      }
      const yamlContent = generateCodexSkillMetadataYaml(entry.name, shortDesc);
      const agentsSubdir = path.join(skillDir, 'agents');
      fs.mkdirSync(agentsSubdir, { recursive: true });
      fs.writeFileSync(path.join(agentsSubdir, 'openai.yaml'), yamlContent);
    } catch (_err) {
      // Fail open — missing or unreadable SKILL.md must not block the install.
    }
  }
}

/**
 * Generate the GSD config block for Codex config.toml.
 * @param {Array<{name: string, description: string}>} agents
 */
function generateCodexConfigBlock(agents, targetDir) {
  // Use absolute paths when targetDir is provided — Codex ≥0.116 requires
  // AbsolutePathBuf for config_file and cannot resolve relative paths.
  const agentsPrefix = targetDir
    ? path.join(targetDir, 'agents').replace(/\\/g, '/')
    : 'agents';
  const lines = [
    GSD_CODEX_MARKER,
    '',
  ];

  for (const { name, description } of agents) {
    // #2727 — Codex 0.124.0 requires [agents.<name>] struct format, not [[agents]] sequence.
    // [[agents]] (introduced in #2645) is rejected by codex-cli 0.124.0 with
    // "invalid type: sequence, expected struct AgentsToml in `agents`".
    lines.push(`[agents.${name}]`);
    lines.push(`description = ${JSON.stringify(description)}`);
    lines.push(`config_file = "${agentsPrefix}/${name}.toml"`);
    lines.push('');
  }

  return lines.join('\n');
}

/**
 * Strip any managed GSD agent sections from a TOML string.
 *
 * Used by the uninstall path (`stripGsdFromCodexConfig`). Removes only what GSD
 * owns; user-authored `[agents.<name>]` and `[[agents]]` entries are preserved
 * so uninstall returns the file to its pre-GSD shape.
 *
 * Handles BOTH shapes so reinstall self-heals configs from all GSD versions:
 *   - Current (#2727): `[agents.gsd-*]` struct tables (Codex 0.120.0+).
 *   - Legacy (#2645): `[[agents]]` array-of-tables whose `name = "gsd-*"`.
 *
 * A section runs from its header to the next `[` header or EOF.
 */
function stripCodexGsdAgentSections(content) {
  // Use the TOML-aware section parser so we never absorb adjacent user-authored
  // tables — even if their headers are indented or otherwise oddly placed.
  const sections = getTomlTableSections(content).filter((section) => {
    // Current `[agents.gsd-<name>]` struct tables (#2727, Codex 0.120.0+).
    if (!section.array && /^agents\.gsd-/.test(section.path)) {
      return true;
    }

    // Legacy `[[agents]]` array-of-tables (#2645) — only strip blocks whose
    // `name = "gsd-..."`, preserving user-authored [[agents]] entries.
    if (section.array && section.path === 'agents') {
      const body = content.slice(section.headerEnd, section.end);
      const nameMatch = body.match(/^[ \t]*name[ \t]*=[ \t]*["']([^"']+)["']/m);
      return Boolean(nameMatch && /^gsd-/.test(nameMatch[1]));
    }

    return false;
  });

  return removeContentRanges(
    content,
    sections.map(({ start, end }) => ({ start, end })),
  );
}

/**
 * Strip GSD sections from Codex config.toml content.
 * Returns cleaned content, or null if file would be empty.
 */
function stripGsdFromCodexConfig(content) {
  const eol = detectLineEnding(content);
  const markerIndex = content.indexOf(GSD_CODEX_MARKER);
  const codexHooksOwnership = getManagedCodexHooksOwnership(content);

  if (markerIndex !== -1) {
    // Has GSD marker — remove everything from marker to EOF
    let before = content.substring(0, markerIndex);
    before = stripCodexHooksFeatureAssignments(before, codexHooksOwnership);
    // Also strip GSD-injected feature keys above the marker (Case 3 inject)
    before = before.replace(/^multi_agent\s*=\s*true\s*(?:\r?\n)?/m, '');
    before = before.replace(/^default_mode_request_user_input\s*=\s*true\s*(?:\r?\n)?/m, '');
    before = before.replace(/^\[features\]\s*\n(?=\[|$)/m, '');
    before = before.replace(/^\[agents\]\s*\n(?=\[|$)/m, '');
    before = before.replace(/^(?:\r?\n)+/, '').trimEnd();
    if (!before) return null;
    return before + eol;
  }

  // No marker but may have GSD-injected feature keys
  let cleaned = content;
  cleaned = stripCodexHooksFeatureAssignments(cleaned, codexHooksOwnership);
  cleaned = cleaned.replace(/^multi_agent\s*=\s*true\s*(?:\r?\n)?/m, '');
  cleaned = cleaned.replace(/^default_mode_request_user_input\s*=\s*true\s*(?:\r?\n)?/m, '');

  // Remove [agents.gsd-*] sections (from header to next section or EOF)
  cleaned = stripCodexGsdAgentSections(cleaned);

  // Remove [features] section if now empty (only header, no keys before next section)
  cleaned = cleaned.replace(/^\[features\]\s*\n(?=\[|$)/m, '');

  // Remove [agents] section if now empty
  cleaned = cleaned.replace(/^\[agents\]\s*\n(?=\[|$)/m, '');

  cleaned = cleaned.replace(/^(?:\r?\n)+/, '').trimEnd();

  if (!cleaned) return null;
  return cleaned + eol;
}

function detectLineEnding(content) {
  const firstNewlineIndex = content.indexOf('\n');
  if (firstNewlineIndex === -1) {
    return '\n';
  }
  return firstNewlineIndex > 0 && content[firstNewlineIndex - 1] === '\r' ? '\r\n' : '\n';
}

function splitTomlLines(content) {
  const lines = [];
  let start = 0;

  while (start < content.length) {
    const newlineIndex = content.indexOf('\n', start);
    if (newlineIndex === -1) {
      lines.push({
        start,
        end: content.length,
        text: content.slice(start),
        eol: '',
      });
      break;
    }

    const hasCr = newlineIndex > start && content[newlineIndex - 1] === '\r';
    const end = hasCr ? newlineIndex - 1 : newlineIndex;
    lines.push({
      start,
      end,
      text: content.slice(start, end),
      eol: hasCr ? '\r\n' : '\n',
    });
    start = newlineIndex + 1;
  }

  return lines;
}

function findTomlCommentStart(line) {
  let i = 0;
  let multilineState = null;

  while (i < line.length) {
    if (multilineState === 'literal') {
      const closeIndex = line.indexOf('\'\'\'', i);
      if (closeIndex === -1) {
        return -1;
      }
      i = closeIndex + 3;
      multilineState = null;
      continue;
    }

    if (multilineState === 'basic') {
      const closeIndex = findMultilineBasicStringClose(line, i);
      if (closeIndex === -1) {
        return -1;
      }
      i = closeIndex + 3;
      multilineState = null;
      continue;
    }

    const ch = line[i];

    if (ch === '#') {
      return i;
    }

    if (ch === '\'') {
      if (line.startsWith('\'\'\'', i)) {
        multilineState = 'literal';
        i += 3;
        continue;
      }
      const close = line.indexOf('\'', i + 1);
      if (close === -1) return -1;
      i = close + 1;
      continue;
    }

    if (ch === '"') {
      if (line.startsWith('"""', i)) {
        multilineState = 'basic';
        i += 3;
        continue;
      }
      i += 1;
      while (i < line.length) {
        if (line[i] === '\\') {
          i += 2;
          continue;
        }
        if (line[i] === '"') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    i += 1;
  }

  return -1;
}

function isEscapedInBasicString(line, index) {
  let slashCount = 0;
  let cursor = index - 1;

  while (cursor >= 0 && line[cursor] === '\\') {
    slashCount += 1;
    cursor -= 1;
  }

  return slashCount % 2 === 1;
}

function findMultilineBasicStringClose(line, startIndex) {
  let searchIndex = startIndex;

  while (searchIndex < line.length) {
    const closeIndex = line.indexOf('"""', searchIndex);
    if (closeIndex === -1) {
      return -1;
    }
    if (!isEscapedInBasicString(line, closeIndex)) {
      return closeIndex;
    }
    searchIndex = closeIndex + 1;
  }

  return -1;
}

function advanceTomlMultilineStringState(line, multilineState) {
  let i = 0;
  let state = multilineState;

  while (i < line.length) {
    if (state === 'literal') {
      const closeIndex = line.indexOf('\'\'\'', i);
      if (closeIndex === -1) {
        return state;
      }
      i = closeIndex + 3;
      state = null;
      continue;
    }

    if (state === 'basic') {
      const closeIndex = findMultilineBasicStringClose(line, i);
      if (closeIndex === -1) {
        return state;
      }
      i = closeIndex + 3;
      state = null;
      continue;
    }

    const ch = line[i];

    if (ch === '#') {
      return state;
    }

    if (ch === '\'') {
      if (line.startsWith('\'\'\'', i)) {
        state = 'literal';
        i += 3;
        continue;
      }
      const close = line.indexOf('\'', i + 1);
      if (close === -1) {
        return state;
      }
      i = close + 1;
      continue;
    }

    if (ch === '"') {
      if (line.startsWith('"""', i)) {
        state = 'basic';
        i += 3;
        continue;
      }
      i += 1;
      while (i < line.length) {
        if (line[i] === '\\') {
          i += 2;
          continue;
        }
        if (line[i] === '"') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    i += 1;
  }

  return state;
}

function parseTomlBracketHeader(line, array) {
  let i = 0;

  while (i < line.length && /\s/.test(line[i])) {
    i += 1;
  }

  const open = array ? '[[' : '[';
  const close = array ? ']]' : ']';
  if (!line.startsWith(open, i)) {
    return null;
  }

  i += open.length;
  const start = i;

  while (i < line.length) {
    if (line[i] === '\'' || line[i] === '"') {
      const quote = line[i];
      i += 1;

      while (i < line.length) {
        if (quote === '"' && line[i] === '\\') {
          i += 2;
          continue;
        }

        if (line[i] === quote) {
          i += 1;
          break;
        }

        i += 1;
      }

      continue;
    }

    if (line.startsWith(close, i)) {
      const rawPath = line.slice(start, i).trim();
      const segments = parseTomlKeyPath(rawPath);
      if (!segments) {
        return null;
      }

      i += close.length;
      while (i < line.length && /\s/.test(line[i])) {
        i += 1;
      }

      if (i < line.length && line[i] !== '#') {
        return null;
      }

      return { path: segments.join('.'), segments, array };
    }

    if (line[i] === '#' || line[i] === '\r' || line[i] === '\n') {
      return null;
    }

    i += 1;
  }

  return null;
}

function parseTomlTableHeader(line) {
  return parseTomlBracketHeader(line, true) || parseTomlBracketHeader(line, false);
}

function findTomlAssignmentEquals(line) {
  let i = 0;

  while (i < line.length) {
    const ch = line[i];

    if (ch === '#') {
      return -1;
    }

    if (ch === '\'') {
      i += 1;
      while (i < line.length) {
        if (line[i] === '\'') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    if (ch === '"') {
      i += 1;
      while (i < line.length) {
        if (line[i] === '\\') {
          i += 2;
          continue;
        }
        if (line[i] === '"') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    if (ch === '=') {
      return i;
    }

    i += 1;
  }

  return -1;
}

function parseTomlKeyPath(keyText) {
  const segments = [];
  let i = 0;

  while (i < keyText.length) {
    while (i < keyText.length && /\s/.test(keyText[i])) {
      i += 1;
    }

    if (i >= keyText.length) {
      break;
    }

    if (keyText[i] === '\'' || keyText[i] === '"') {
      const quote = keyText[i];
      let segment = '';
      let closed = false;
      i += 1;

      while (i < keyText.length) {
        if (quote === '"' && keyText[i] === '\\') {
          if (i + 1 >= keyText.length) {
            return null;
          }
          segment += keyText[i + 1];
          i += 2;
          continue;
        }

        if (keyText[i] === quote) {
          i += 1;
          closed = true;
          break;
        }

        segment += keyText[i];
        i += 1;
      }

      if (!closed) {
        return null;
      }

      segments.push(segment);
    } else {
      const match = keyText.slice(i).match(/^[A-Za-z0-9_-]+/);
      if (!match) {
        return null;
      }
      segments.push(match[0]);
      i += match[0].length;
    }

    while (i < keyText.length && /\s/.test(keyText[i])) {
      i += 1;
    }

    if (i >= keyText.length) {
      break;
    }

    if (keyText[i] !== '.') {
      return null;
    }

    i += 1;
  }

  return segments.length > 0 ? segments : null;
}

function parseTomlKey(line) {
  const header = parseTomlTableHeader(line);
  if (header) {
    return null;
  }

  const equalsIndex = findTomlAssignmentEquals(line);
  if (equalsIndex === -1) {
    return null;
  }

  const raw = line.slice(0, equalsIndex).trim();
  const segments = parseTomlKeyPath(raw);
  if (!segments) {
    return null;
  }

  return { raw, segments };
}

function getTomlLineRecords(content) {
  const lines = splitTomlLines(content);
  const records = [];
  let currentTablePath = null;
  let multilineState = null;

  for (const line of lines) {
    const startsInMultilineString = multilineState !== null;
    const record = {
      ...line,
      startsInMultilineString,
      tablePath: currentTablePath,
      tableHeader: null,
      keySegments: null,
    };

    if (!startsInMultilineString) {
      const header = parseTomlTableHeader(line.text);
      if (header) {
        record.tableHeader = header;
        currentTablePath = header.path;
      } else {
        const key = parseTomlKey(line.text);
        record.keySegments = key ? key.segments : null;
        record.keyRaw = key ? key.raw : null;
      }
    }

    multilineState = advanceTomlMultilineStringState(line.text, multilineState);
    records.push(record);
  }

  return records;
}

function getTomlTableSections(content) {
  const headerLines = getTomlLineRecords(content).filter((record) => record.tableHeader);

  return headerLines.map((record, index) => ({
    path: record.tableHeader.path,
    // segments preserves the true parsed key count so callers that need to
    // distinguish a 2-segment path like hooks."before.tool" from a 3-segment
    // path like hooks.SessionStart.hooks can do so without splitting on dots
    // (which misclassifies quoted key names that contain dot characters).
    segments: record.tableHeader.segments,
    array: record.tableHeader.array,
    start: record.start,
    headerEnd: record.end + record.eol.length,
    end: index + 1 < headerLines.length ? headerLines[index + 1].start : content.length,
  }));
}

function collapseTomlBlankLines(content) {
  const eol = detectLineEnding(content);
  return content.replace(/(?:\r?\n){3,}/g, eol + eol);
}

function removeContentRanges(content, ranges) {
  const normalizedRanges = ranges
    .filter((range) => range && range.start < range.end)
    .sort((a, b) => a.start - b.start);

  if (normalizedRanges.length === 0) {
    return content;
  }

  const mergedRanges = [{ ...normalizedRanges[0] }];

  for (let i = 1; i < normalizedRanges.length; i += 1) {
    const current = normalizedRanges[i];
    const previous = mergedRanges[mergedRanges.length - 1];

    if (current.start <= previous.end) {
      previous.end = Math.max(previous.end, current.end);
      continue;
    }

    mergedRanges.push({ ...current });
  }

  let cleaned = '';
  let cursor = 0;

  for (const range of mergedRanges) {
    cleaned += content.slice(cursor, range.start);
    cursor = range.end;
  }

  cleaned += content.slice(cursor);
  return cleaned;
}

function stripCodexHooksFeatureAssignments(content, ownership = null) {
  const lineRecords = getTomlLineRecords(content);
  const tableSections = getTomlTableSections(content);
  const removalRanges = [];
  const featuresSection = tableSections.find((section) => !section.array && section.path === 'features');
  const shouldStripSectionKey = ownership === 'section' || ownership === 'all';
  const shouldStripRootDottedKey = ownership === 'root_dotted' || ownership === 'all';

  if (featuresSection && shouldStripSectionKey) {
    const sectionRecords = lineRecords.filter((record) =>
      !record.tableHeader &&
      record.start >= featuresSection.headerEnd &&
      record.end + record.eol.length <= featuresSection.end
    );

    const codexHookRecords = sectionRecords.filter((record) =>
      !record.startsInMultilineString &&
      record.keySegments &&
      record.keySegments.length === 1 &&
      isCodexHooksFeatureKey(record.keySegments[0])
    );

    for (const record of codexHookRecords) {
      removalRanges.push({
        start: record.start,
        end: findTomlAssignmentBlockEnd(content, record),
      });
    }

    if (codexHookRecords.length > 0) {
      const removedStarts = new Set(codexHookRecords.map((record) => record.start));
      const hasRemainingContent = sectionRecords.some((record) => {
        if (removedStarts.has(record.start)) {
          return false;
        }

        const trimmed = record.text.trim();
        return trimmed !== '' && !trimmed.startsWith('#');
      });
      const hasRemainingComments = sectionRecords.some((record) => {
        if (removedStarts.has(record.start)) {
          return false;
        }

        return record.text.trim().startsWith('#');
      });

      if (!hasRemainingContent && !hasRemainingComments) {
        removalRanges.push({
          start: featuresSection.start,
          end: featuresSection.end,
        });
      }
    }
  }

  if (shouldStripRootDottedKey) {
    const rootCodexHookRecords = lineRecords.filter((record) =>
      !record.tableHeader &&
      !record.startsInMultilineString &&
      record.tablePath === null &&
      record.keySegments &&
      record.keySegments.length === 2 &&
      record.keySegments[0] === 'features' &&
      isCodexHooksFeatureKey(record.keySegments[1])
    );

    for (const record of rootCodexHookRecords) {
      removalRanges.push({
        start: record.start,
        end: findTomlAssignmentBlockEnd(content, record),
      });
    }
  }

  return removeContentRanges(content, removalRanges);
}

function getManagedCodexHooksOwnership(content) {
  const markerIndex = content.indexOf(GSD_CODEX_MARKER);
  if (markerIndex === -1) {
    return null;
  }

  const afterMarker = content.slice(markerIndex + GSD_CODEX_MARKER.length);
  const match = afterMarker.match(/^\r?\n# GSD codex_hooks ownership: (section|root_dotted)\r?\n/);
  return match ? match[1] : null;
}

function setManagedCodexHooksOwnership(content, ownership) {
  const markerIndex = content.indexOf(GSD_CODEX_MARKER);
  if (markerIndex === -1) {
    return content;
  }

  const eol = detectLineEnding(content);
  const markerEnd = markerIndex + GSD_CODEX_MARKER.length;
  const afterMarker = content.slice(markerEnd);
  const normalizedAfterMarker = afterMarker.replace(
    /^\r?\n# GSD codex_hooks ownership: (?:section|root_dotted)\r?\n/,
    eol
  );

  if (!ownership) {
    return content.slice(0, markerEnd) + normalizedAfterMarker;
  }

  const remainder = normalizedAfterMarker.replace(/^\r?\n/, '');
  return content.slice(0, markerEnd) +
    eol +
    `${GSD_CODEX_HOOKS_OWNERSHIP_PREFIX}${ownership}${eol}` +
    remainder;
}

function isLegacyGsdAgentsSection(body) {
  const lineRecords = getTomlLineRecords(body);
  const legacyKeys = new Set(['max_threads', 'max_depth']);
  let sawLegacyKey = false;

  for (const record of lineRecords) {
    if (record.startsInMultilineString) {
      return false;
    }

    if (record.tableHeader) {
      return false;
    }

    const trimmed = record.text.trim();
    if (!trimmed || trimmed.startsWith('#')) {
      continue;
    }

    if (!record.keySegments || record.keySegments.length !== 1 || !legacyKeys.has(record.keySegments[0])) {
      return false;
    }

    sawLegacyKey = true;
  }

  return sawLegacyKey;
}

function stripLeakedGsdCodexSections(content) {
  // Defensive precedence (#2760): we own the `agents` namespace under our
  // managed `gsd-*` names, and the legacy bare-table and sequence forms
  // (`[agents]`, `[[agents]]`) are invalid in the current Codex schema —
  // they trigger "invalid type: ..., expected struct AgentsToml" and break
  // every Codex CLI invocation. They MUST never coexist with the new
  // `[agents.<name>]` struct format we now emit, so install-time always
  // purges them regardless of GSD marker presence. Users who had legitimate
  // user-authored `[[agents]]` entries before are already broken on Codex
  // ≥0.124 — purging is the only path to a loadable config.
  const leakedSections = getTomlTableSections(content)
    .filter((section) => {
      // Legacy [agents.gsd-<name>] map tables (pre-#2645).
      if (!section.array && section.path.startsWith('agents.gsd-')) return true;

      // ANY bare [agents] single-bracket table — invalid in current Codex
      // schema, always purged at install time (#2760). Previously gated
      // on `isLegacyGsdAgentsSection`, which missed bare tables holding
      // arbitrary user keys (`default = "..."`, etc.) that still produce
      // the AgentsToml type error.
      if (!section.array && section.path === 'agents') return true;

      // ANY [[agents]] array-of-tables — invalid in current Codex schema,
      // always purged at install time (#2760). Previously gated on
      // `name = "gsd-..."` which preserved user-authored entries that are
      // themselves rejected by Codex 0.124+.
      if (section.array && section.path === 'agents') return true;

      return false;
    });

  if (leakedSections.length === 0) {
    return content;
  }

  let cleaned = '';
  let cursor = 0;

  for (const section of leakedSections) {
    cleaned += content.slice(cursor, section.start);
    cursor = section.end;
  }

  cleaned += content.slice(cursor);
  return collapseTomlBlankLines(cleaned);
}

/**
 * Strip GSD-managed legacy Codex hook blocks from a config.toml string
 * using the TOML AST already used elsewhere in this file
 * (`getTomlTableSections` + `removeContentRanges`). The earlier regex-based
 * implementation required a precise key order, exact single-space padding
 * around `=`, and exactly one blank line between Shape 4's parent/child
 * tables — any deviation (an extra blank line, key reorder, an added
 * `timeout` key, `event="SessionStart"` without spaces) silently leaked the
 * stale block, sometimes corrupting the file by leaving orphaned key=value
 * lines outside any table.
 *
 * The structural approach: find every `hooks*` table whose body contains a
 * `command = "...gsd-(check-update|update-check).js"` value, remove its
 * exact byte range, and additionally remove any orphaned parent
 * `[[hooks.SessionStart]]` whose body becomes empty as a result (Shape 4).
 * The leading `# GSD Hooks` header line is swallowed by extending the
 * removal range backward through any single preceding comment line.
 *
 * Pure function, exported for test coverage. Returns the input unchanged
 * if no GSD-managed hook section is present.
 */
function stripStaleGsdHookBlocks(configContent) {
  const sections = getTomlTableSections(configContent);
  const lineRecords = getTomlLineRecords(configContent);
  const hookSections = sections.filter(
    (s) => s.path === 'hooks' || s.path.startsWith('hooks.')
  );
  if (hookSections.length === 0) {
    return configContent;
  }

  // A section is GSD-managed if any structural `command` key inside its
  // body parses to a string whose basename matches `gsd-(check-update|
  // update-check).js`. The TOML line parser already classified each line's
  // `keySegments`, so we never inspect raw text — this handles arbitrary
  // whitespace, key reordering, and additional keys robustly.
  function sectionHasStaleCommand(section) {
    const records = lineRecords.filter(
      (r) => !r.startsInMultilineString
        && !r.tableHeader
        && r.start >= section.headerEnd
        && r.end + r.eol.length <= section.end
        && r.keySegments
        && r.keySegments.length === 1
        && r.keySegments[0] === 'command'
    );
    for (const record of records) {
      const equalsIndex = findTomlAssignmentEquals(record.text);
      if (equalsIndex === -1) continue;
      let parsed;
      try {
        parsed = parseTomlValue(record.text, equalsIndex + 1);
      } catch {
        continue;
      }
      if (typeof parsed.value !== 'string') continue;
      if (isManagedHookCommand(parsed.value, {
        surface: 'codex-toml',
        includeLegacyAliases: true,
      })) {
        return true;
      }
    }
    return false;
  }

  const stale = new Set(hookSections.filter(sectionHasStaleCommand));
  if (stale.size === 0) {
    return configContent;
  }

  // Shape 4: a `[[hooks.SessionStart]]` event-table whose body is empty and
  // whose immediately following section is a stale child handler table
  // (`[[hooks.SessionStart.hooks]]`) becomes orphaned once the child is
  // stripped. Detect emptiness via line records — no key/value lines and no
  // non-blank, non-comment text between this section's header and the next.
  function sectionBodyHasContent(section) {
    return lineRecords.some(
      (r) => !r.startsInMultilineString
        && !r.tableHeader
        && r.start >= section.headerEnd
        && r.end + r.eol.length <= section.end
        && r.text.trim() !== ''
        && !r.text.trim().startsWith('#')
    );
  }
  for (let i = 0; i < sections.length; i += 1) {
    const parent = sections[i];
    if (stale.has(parent)) continue;
    if (!parent.array || parent.path !== 'hooks.SessionStart') continue;
    if (sectionBodyHasContent(parent)) continue;
    const next = sections[i + 1];
    if (next && stale.has(next) && next.path.startsWith('hooks.SessionStart.')) {
      stale.add(parent);
    }
  }

  // Each removal range starts at the table header. If the immediately
  // preceding line is the GSD marker comment `# GSD Hooks` (and is not part
  // of an already-removed section), extend the range backward to swallow it
  // — preserves cleanliness on round-trip strip+rewrite.
  const ranges = [];
  for (const section of stale) {
    let start = section.start;
    const headerLineIdx = lineRecords.findIndex((r) => r.start === section.start);
    const prev = headerLineIdx > 0 ? lineRecords[headerLineIdx - 1] : null;
    if (prev && !prev.startsInMultilineString && prev.text.trim() === '# GSD Hooks') {
      start = prev.start;
    }
    ranges.push({ start, end: section.end });
  }

  return collapseTomlBlankLines(removeContentRanges(configContent, ranges));
}

/**
 * Migrate legacy Codex [hooks] map format to [[hooks]] array-of-tables format.
 *
 * Codex 0.124.0 changed from the old map-style hooks config:
 *   [hooks]
 *     [hooks.shell]
 *     command = "..."
 *
 * to the new array-of-tables format. #2760 CR5 finding 3 — emit the
 * namespaced AoT shape directly so a mixed flat + namespaced layout never
 * arises post-install:
 *   [[hooks.shell]]
 *   command = "..."
 *
 * This function detects any non-array hooks sections in the config and
 * converts them to the namespaced `[[hooks.<TYPE>]]` array-of-tables form,
 * preserving all key-value pairs and user comments. Bare [hooks] container
 * sections (no key-value content) are dropped. User-authored AoT entries are
 * left untouched.
 *
 * Returns the migrated content, or the original content unchanged if no
 * legacy hooks sections were found.
 */
function migrateCodexHooksMapFormat(content) {
  const sections = getTomlTableSections(content);

  // Find all non-array hooks sections: bare [hooks] container or [hooks.TYPE] event tables.
  // Use section.segments (parsed key count) rather than section.path.startsWith() so that
  // nested handler tables like [hooks.SessionStart.hooks] (3 segments) are not mistakenly
  // included and re-emitted as an event named "SessionStart.hooks".
  // Exclude hooks.state and hooks.state.* — these are Codex's persistent hook-trust
  // namespace (Codex CLI 0.130.0+) and use regular-table shape, never AoT.
  const legacyMapSections = sections.filter(
    (section) => !section.array && (
      section.path === 'hooks' ||
      (section.path.startsWith('hooks.') && section.segments.length === 2 &&
        section.path !== 'hooks.state' && !section.path.startsWith('hooks.state.'))
    )
  );

  // Find flat [[hooks]] array-of-tables entries (path === 'hooks', array === true).
  // These are incompatible with [[hooks.<EVENT>]] namespaced form — both cannot
  // coexist in the same TOML file because `hooks` cannot be simultaneously an
  // array and a table. Migrate each flat entry to [[hooks.<EVENT>]] form using
  // the `event` key as the event name.
  const flatAotSections = sections.filter(
    (section) => section.array && section.path === 'hooks'
  );

  // Find [[hooks.TYPE]] namespaced AoT entries that carry handler fields
  // (command, type, timeout, statusMessage) at event-entry level but have no
  // [[hooks.TYPE.hooks]] sub-table. This is the pre-#2773 single-block shape
  // that Codex 0.124.0+ rejects. Promote them to the two-level nested form.
  // Entries that already have a [[hooks.TYPE.hooks]] sub-table are left untouched.
  // Matcher-only entries (no handler fields) are intentionally valid and skipped.
  const STALE_HANDLER_FIELD_PATTERN = /^\s*(?:command|type|timeout|statusMessage)\s*=/m;
  const staleNamespacedAotSections = sections.filter((section) => {
    if (!section.array) return false;
    if (!section.path.startsWith('hooks.')) return false;
    // [[hooks.TYPE.hooks]] sub-tables have 3 parsed segments — skip them.
    // Use section.segments (true parsed key count) rather than splitting
    // section.path on '.', which misclassifies quoted event names that contain
    // dots (e.g. [[hooks."before.tool"]] has segments ['hooks','before.tool']
    // but path 'hooks.before.tool' would split into 3 parts).
    if (section.segments.length !== 2) return false;
    // Must carry at least one handler field at event-entry level.
    const body = content.slice(section.headerEnd, section.end);
    if (!STALE_HANDLER_FIELD_PATTERN.test(body)) return false;
    // Don't migrate when the nested [[hooks.TYPE.hooks]] sub-table already exists.
    const subPath = section.path + '.hooks';
    return !sections.some((s) => s.array && s.path === subPath);
  });

  if (legacyMapSections.length === 0 && flatAotSections.length === 0 && staleNamespacedAotSections.length === 0) {
    return content;
  }

  const eol = detectLineEnding(content);

  // Helper: parse a hooks body into event-level and handler-level entries,
  // returning { eventEntries, handlerEntries, hasExplicitType }.
  // Event-level keys: matcher. Everything else is handler-level.
  // The `event` key (used in flat [[hooks]] blocks) is consumed as the type
  // name and excluded from both levels.
  const EVENT_LEVEL_KEYS = new Set(['matcher']);
  function parseHooksBody(body, skipKeys = new Set()) {
    const bodyLines = body.split(/\r?\n/);
    const eventEntries = [];
    const handlerEntries = [];
    let hasExplicitType = false;
    for (const line of bodyLines) {
      const trimmed = line.trim();
      if (!trimmed || trimmed.startsWith('#')) continue;
      // Use parseTomlKey so hyphenated keys (e.g. status-message) and quoted
      // keys are recognised — the old /^([\w.]+)\s*=/ regex silently dropped them.
      const parsed = parseTomlKey(trimmed);
      if (!parsed) continue;
      // Hook body keys are always single-segment; use segments[0] for the name.
      const key = parsed.segments[0];
      if (skipKeys.has(key)) continue;
      if (key === 'type') {
        hasExplicitType = true;
        handlerEntries.push(trimmed);
      } else if (EVENT_LEVEL_KEYS.has(key)) {
        eventEntries.push(trimmed);
      } else {
        handlerEntries.push(trimmed);
      }
    }
    return { eventEntries, handlerEntries, hasExplicitType };
  }

  // TOML key quoting: bare keys may only contain [A-Za-z0-9_-]. Event names
  // containing spaces, dots, or other punctuation must be wrapped in double-
  // quoted TOML strings with backslash and double-quote characters escaped.
  // Using raw event names in [[hooks.${type}]] headers produces invalid TOML
  // for any non-bare-key character (e.g. "Before Tool" → [[hooks.Before Tool]]).
  function tomlBareKey(key) {
    if (/^[A-Za-z0-9_-]+$/.test(key)) return key;
    return '"' + key.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
  }

  function buildNestedBlock(type, body, skipKeys = new Set()) {
    const quotedType = tomlBareKey(type);
    const { eventEntries, handlerEntries, hasExplicitType } = parseHooksBody(body, skipKeys);
    const eventBody = eventEntries.length > 0 ? eventEntries.join(eol) + eol : '';
    // If no handler fields were found (e.g. matcher-only entry), do not synthesise
    // an empty [[hooks.TYPE.hooks]] block — that would produce structurally valid
    // TOML but semantically broken output (a handler entry with no command).
    if (handlerEntries.length === 0) {
      return `[[hooks.${quotedType}]]${eol}${eventBody}`;
    }
    if (!hasExplicitType) handlerEntries.unshift('type = "command"');
    const handlerBody = handlerEntries.join(eol) + eol;
    return `[[hooks.${quotedType}]]${eol}${eventBody}${eol}[[hooks.${quotedType}.hooks]]${eol}${handlerBody}`;
  }

  // Extract the event name from a flat [[hooks]] section body.
  // Returns null if no `event` key is found, if the value is an empty string, or if
  // the quoting is unrecognised. Both TOML double-quoted ("...") and single-quoted
  // ('...') strings are accepted. An empty event string (event = "" or event = '')
  // is explicitly rejected — it cannot be meaningfully namespaced and is left untouched.
  function extractFlatHookEventName(body) {
    const TOML_EVENT_CAPTURE = /^\s*event\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/m;
    const m = body.match(TOML_EVENT_CAPTURE);
    if (!m) return null;
    const name = (m[1] ?? m[2] ?? '').trim();
    return name || null;
  }

  const migratedFlatAotSections = flatAotSections.filter((section) => {
    const body = content.slice(section.headerEnd, section.end);
    return extractFlatHookEventName(body) !== null;
  });

  const legacyHooksSections = [...legacyMapSections, ...migratedFlatAotSections, ...staleNamespacedAotSections];

  // Remove all legacy hooks sections from the content
  let result = removeContentRanges(
    content,
    legacyHooksSections.map(({ start, end }) => ({ start, end })),
  );
  result = collapseTomlBlankLines(result);

  // Map-format blocks ([hooks.TYPE]) are inserted at the position of the first
  // remaining table section (preserving their relative placement in the file).
  // Flat AoT blocks ([[hooks]] with event = "...") are always APPENDED because
  // flat [[hooks]] entries only appear at the END of a TOML file (AoT cannot
  // precede a regular table), and inserting before the first table would push
  // them above [features] / [model] etc., corrupting relative ordering.
  const mapOnlyBlocks = legacyMapSections
    .filter((s) => s.path !== 'hooks')   // skip bare [hooks] container
    .map((s) => {
      const body = content.slice(s.headerEnd, s.end);
      // #3346: when the legacy `[hooks.<X>]` body declares `event = "..."`,
      // prefer that as the event-name leaf key. The path segment <X> may be
      // a `<file>:<event>:<line>:<col>` location identifier (Codex pre-AoT
      // wrote those as table keys), which is not a valid leaf event name —
      // emitting it verbatim produces a TOML key chain Codex 0.124.0+ rejects.
      const bodyEvent = extractFlatHookEventName(body);
      const type = bodyEvent !== null ? bodyEvent : s.path.slice('hooks.'.length);
      const skipKeys = bodyEvent !== null ? new Set(['event']) : new Set();
      return buildNestedBlock(type, body, skipKeys);
    });

  // Stale namespaced AoT blocks: [[hooks.TYPE]] entries with handler fields at
  // event-entry level (no .hooks sub-table). Treated like map-format blocks —
  // inserted before the first remaining table section.
  const staleNamespacedAotBlocks = staleNamespacedAotSections.map((s) => {
    const body = content.slice(s.headerEnd, s.end);
    // #3346: see note in mapOnlyBlocks — body `event = "..."` wins over the
    // raw path segment when both are present.
    const bodyEvent = extractFlatHookEventName(body);
    const type = bodyEvent !== null ? bodyEvent : s.path.slice('hooks.'.length);
    const skipKeys = bodyEvent !== null ? new Set(['event']) : new Set();
    return buildNestedBlock(type, body, skipKeys);
  });

  const flatAotBlocks = migratedFlatAotSections.map((s) => {
    const body = content.slice(s.headerEnd, s.end);
    const eventName = extractFlatHookEventName(body);
    if (!eventName) return '';
    return buildNestedBlock(eventName, body, new Set(['event']));
  }).filter(Boolean);

  // Insert map-format and stale-namespaced-AoT conversions before the first
  // remaining table section (both share the same placement strategy).
  const allMapStyleBlocks = [...mapOnlyBlocks, ...staleNamespacedAotBlocks];
  if (allMapStyleBlocks.length > 0) {
    const insertionText = allMapStyleBlocks.join('');
    const remainingSections = getTomlTableSections(result);
    if (remainingSections.length > 0) {
      const firstTable = remainingSections[0];
      const before = result.slice(0, firstTable.start);
      const after = result.slice(firstTable.start);
      const needsLeadingGap = before.length > 0 && !before.endsWith(eol + eol);
      const needsTrailingGap = after.length > 0 && !insertionText.endsWith(eol + eol);
      result = before +
        (needsLeadingGap ? eol : '') +
        insertionText +
        (needsTrailingGap ? eol : '') +
        after;
    } else {
      const needsGap = result.length > 0 && !result.endsWith(eol + eol);
      result = result + (needsGap ? eol : '') + insertionText;
    }
  }

  // Insert flat-AoT conversions before the GSD managed marker (if present) so
  // the migrated user hooks stay in the "user" portion of the file and are not
  // swept away when stripGsdFromCodexConfig strips from the marker to EOF.
  // If no marker exists, append at the end of the file.
  if (flatAotBlocks.length > 0) {
    const insertionText = flatAotBlocks.join('');
    const markerIdx = result.indexOf(GSD_CODEX_MARKER);
    if (markerIdx !== -1) {
      const before = result.slice(0, markerIdx).trimEnd();
      const after = result.slice(markerIdx);
      result = before + eol + eol + insertionText + eol + after;
    } else {
      const needsGap = result.length > 0 && !result.endsWith(eol + eol);
      result = result + (needsGap ? eol : '') + insertionText;
    }
  }

  return result;
}

/**
 * Detect whether the user already uses the namespaced AoT hooks form
 * (`[[hooks.<EVENT>]]`) for the given event in the config. When true,
 * the GSD-managed hook block must be emitted in the same shape so it
 * coexists cleanly — mixing `[[hooks]]` (flat) with `[[hooks.SessionStart]]`
 * (namespaced) in the same file confuses round-trip writers and can
 * produce a config that Codex rejects (#2760, defect 3).
 */
function hasUserNamespacedAotHooks(content, event) {
  const sections = getTomlTableSections(content);
  return sections.some(
    (section) => section.array && section.path === `hooks.${event}`
  );
}

/**
 * Parse a TOML value RHS expression starting at index `i` of `text`.
 * Returns { value, end } on success or throws on parse failure.
 *
 * Supports the value forms GSD emits or that real Codex configs commonly use:
 *   - basic strings ("…" with simple escapes)
 *   - literal strings ('…')
 *   - booleans (true / false)
 *   - integers (optional sign, decimal digits)
 *   - inline arrays of the above
 *   - inline tables { k = v, … }
 *
 * This is intentionally not a complete TOML implementation — it is the
 * minimal value grammar required to validate Codex config structure and to
 * back behavioral assertions in tests (#2760).
 */
function parseTomlValue(text, i) {
  // Skip leading whitespace.
  while (i < text.length && (text[i] === ' ' || text[i] === '\t')) {
    i += 1;
  }
  if (i >= text.length) {
    throw new Error('expected value, got end of input');
  }

  const ch = text[i];

  // Basic string
  if (ch === '"') {
    if (text.startsWith('"""', i)) {
      const close = findMultilineBasicStringClose(text, i + 3);
      if (close === -1) {
        throw new Error('unterminated multi-line basic string');
      }
      const raw = text.slice(i + 3, close);
      return { value: raw.replace(/^\r?\n/, ''), end: close + 3 };
    }
    let j = i + 1;
    let out = '';
    while (j < text.length) {
      const c = text[j];
      if (c === '\\') {
        const next = text[j + 1];
        if (next === 'n') { out += '\n'; j += 2; continue; }
        if (next === 't') { out += '\t'; j += 2; continue; }
        if (next === 'r') { out += '\r'; j += 2; continue; }
        if (next === '\\') { out += '\\'; j += 2; continue; }
        if (next === '"') { out += '"'; j += 2; continue; }
        if (next === '/') { out += '/'; j += 2; continue; }
        // Pass-through unrecognized escape (Codex/GSD don't use these).
        out += next === undefined ? '' : next;
        j += 2;
        continue;
      }
      if (c === '"') {
        return { value: out, end: j + 1 };
      }
      out += c;
      j += 1;
    }
    throw new Error('unterminated basic string');
  }

  // Literal string
  if (ch === '\'') {
    if (text.startsWith('\'\'\'', i)) {
      const close = text.indexOf('\'\'\'', i + 3);
      if (close === -1) throw new Error('unterminated multi-line literal string');
      return { value: text.slice(i + 3, close).replace(/^\r?\n/, ''), end: close + 3 };
    }
    const close = text.indexOf('\'', i + 1);
    if (close === -1) throw new Error('unterminated literal string');
    return { value: text.slice(i + 1, close), end: close + 1 };
  }

  // Boolean
  if (text.startsWith('true', i) && !/[A-Za-z0-9_-]/.test(text[i + 4] || '')) {
    return { value: true, end: i + 4 };
  }
  if (text.startsWith('false', i) && !/[A-Za-z0-9_-]/.test(text[i + 5] || '')) {
    return { value: false, end: i + 5 };
  }

  // Inline array
  if (ch === '[') {
    const arr = [];
    let j = i + 1;
    while (true) {
      while (j < text.length && /[\s\r\n]/.test(text[j])) j += 1;
      if (j >= text.length) throw new Error('unterminated inline array');
      if (text[j] === ']') return { value: arr, end: j + 1 };
      if (text[j] === '#') {
        const nl = text.indexOf('\n', j);
        j = nl === -1 ? text.length : nl + 1;
        continue;
      }
      const parsed = parseTomlValue(text, j);
      arr.push(parsed.value);
      j = parsed.end;
      while (j < text.length && /[\s\r\n]/.test(text[j])) j += 1;
      if (j < text.length && text[j] === ',') {
        j += 1;
        continue;
      }
      while (j < text.length && /[\s\r\n]/.test(text[j])) j += 1;
      if (text[j] === ']') return { value: arr, end: j + 1 };
      throw new Error(`expected , or ] in inline array at offset ${j}`);
    }
  }

  // Inline table
  if (ch === '{') {
    const obj = {};
    let j = i + 1;
    while (true) {
      while (j < text.length && /[\s\r\n]/.test(text[j])) j += 1;
      if (text[j] === '}') return { value: obj, end: j + 1 };
      const keyMatch = text.slice(j).match(/^([A-Za-z0-9_-]+|"[^"]*"|'[^']*')\s*=\s*/);
      if (!keyMatch) throw new Error(`expected key in inline table at offset ${j}`);
      let rawKey = keyMatch[1];
      if ((rawKey.startsWith('"') && rawKey.endsWith('"')) || (rawKey.startsWith('\'') && rawKey.endsWith('\''))) {
        rawKey = rawKey.slice(1, -1);
      }
      j += keyMatch[0].length;
      const parsed = parseTomlValue(text, j);
      obj[rawKey] = parsed.value;
      j = parsed.end;
      while (j < text.length && /[\s\r\n]/.test(text[j])) j += 1;
      if (text[j] === ',') { j += 1; continue; }
      if (text[j] === '}') return { value: obj, end: j + 1 };
      throw new Error(`expected , or } in inline table at offset ${j}`);
    }
  }

  // Number — integer or TOML 1.0 float. (#2760 CR4 finding 3 required explicit
  // rejection of floats; #3245 inverts that: Codex CLI's serde schema requires
  // f64 for tool_timeout_sec / startup_timeout_sec, so integers are what Codex
  // rejects. Accept TOML floats and store as JS Number.)
  //
  // Still rejected: date/time literals (`-`, `:`, `T`, `Z` after integer prefix)
  // and hex/oct/bin literals (`0x`, `0o`, `0b` — `x`, `o`, `b` fall through to
  // the unsupported-value throw below because the integer-part pattern won't match `x`).
  // TOML 1.0 §2: underscores in numeric literals are only allowed BETWEEN
  // digits (each underscore must have a digit on both sides). The pre-check
  // regex uses (?:_?\d)* rather than [\d_]* so `1__0`, `1_.0`, and `1._0`
  // are rejected before normalization silently hides them.
  //
  // TOML 1.0 §2 (integer part): the integer part of a number must follow
  // decimal-integer rules — no leading zeros except the value 0 itself.
  // `01`, `00`, `01.5`, `00e2`, `+01`, `-01` are therefore all invalid.
  // The pre-check and float regexes use (0|[1-9](?:_?\d)*) for the integer
  // part so that `01` and `00` are rejected (k021 sibling rule).
  const numMatch = text.slice(i).match(/^[+-]?(0|[1-9](?:_?\d)*)/);
  if (numMatch) {
    const afterInt = text[i + numMatch[0].length];
    // Reject date/time separators that cannot be part of a float.
    if (afterInt !== undefined && /[:\-TZ]/.test(afterInt)) {
      throw new Error(
        `unsupported TOML value at offset ${i}: dates and times are not supported (got ${text.slice(i, i + 20)})`
      );
    }
    // Accept float: optional decimal part, optional exponent part.
    // Each segment uses (?:_?\d)* so underscores are only between digits.
    // Integer part uses (0|[1-9](?:_?\d)*) to reject leading zeros per TOML 1.0.
    const floatMatch = text.slice(i).match(
      /^[+-]?(0|[1-9](?:_?\d)*)(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/
    );
    const raw = floatMatch ? floatMatch[0] : numMatch[0];
    const normalized = raw.replace(/_/g, '');
    const n = Number(normalized);
    if (!Number.isFinite(n)) throw new Error(`invalid number: ${raw}`);
    return { value: n, end: i + raw.length };
  }

  throw new Error(`unsupported value at offset ${i}: ${text.slice(i, i + 20)}`);
}

/**
 * Parse TOML content into a JavaScript object. Throws on malformed input.
 *
 * Handles `[table]`, `[[array.of.tables]]`, dotted key paths, and the value
 * forms supported by parseTomlValue. Sufficient for validating Codex config
 * structure and for behavioral test assertions in #2760 — not a general
 * TOML implementation.
 */
function parseTomlToObject(content) {
  const root = {};
  const records = getTomlLineRecords(content);
  // Tracks the *object* (not path) that subsequent key=value lines target.
  let currentTable = root;

  // #2760 CR5 finding 2 — track shape and definition status of every path so
  // we can reject duplicate header redeclarations, shape mismatches, and
  // duplicate keys per real TOML 1.0 semantics. Without this, walkPath
  // silently reuses existing tables and assignment overwrites existing keys —
  // a real TOML parser would refuse the file.
  //
  // pathShape: dotted path -> 'table' | 'array' | 'inline_parent' | 'key'
  //   - 'table' — declared via [a.b]
  //   - 'array' — declared via [[a.b]] (path is the array itself; each
  //               element is its own implicit table)
  //   - 'inline_parent' — created implicitly while walking parents
  //   - 'key'   — assigned a scalar value
  // declaredHeaders: set of dotted paths explicitly declared via [hdr] (not
  //   [[arr]]) — used to reject duplicate [a] / [a] sections.
  // tableKeys: dotted-path -> Set<string> of keys assigned in that exact
  //   table instance. For [[arr]] elements we use a per-element marker.
  const pathShape = new Map();
  const declaredHeaders = new Set();
  const tableKeys = new Map();
  // currentTableId — string identifier for the current table instance, used
  // as the key into tableKeys so that key uniqueness is per-table-instance
  // (each [[arr]] element gets its own id).
  let currentTableId = '__root__';
  pathShape.set('__root__', 'table');
  tableKeys.set('__root__', new Set());

  function ensureKeySet(id) {
    if (!tableKeys.has(id)) tableKeys.set(id, new Set());
    return tableKeys.get(id);
  }

  function walkPath(segments, { creatingArrayElement = false } = {}) {
    let node = root;
    const parents = segments.slice(0, -1);
    const last = segments[segments.length - 1];

    for (let p = 0; p < parents.length; p += 1) {
      const seg = parents[p];
      const partialPath = parents.slice(0, p + 1).join('.');
      if (node[seg] === undefined) {
        node[seg] = {};
        if (!pathShape.has(partialPath)) {
          pathShape.set(partialPath, 'inline_parent');
        }
      } else if (Array.isArray(node[seg])) {
        // Walk into the latest element of an array-of-tables.
        node = node[seg][node[seg].length - 1];
        continue;
      } else if (typeof node[seg] !== 'object' || node[seg] === null) {
        throw new Error(`path segment ${seg} is not a table`);
      }
      node = node[seg];
    }

    const fullPath = segments.join('.');

    if (creatingArrayElement) {
      const existingShape = pathShape.get(fullPath);
      if (node[last] === undefined) {
        node[last] = [];
        pathShape.set(fullPath, 'array');
      } else if (!Array.isArray(node[last])) {
        throw new Error(
          `duplicate or shape-mismatched table header at ${fullPath}: ` +
          `cannot redefine as array of tables (previously seen as ${existingShape || 'table'})`
        );
      } else if (existingShape && existingShape !== 'array') {
        throw new Error(
          `duplicate or shape-mismatched table header at ${fullPath}: ` +
          `previously seen as ${existingShape}, cannot extend as array of tables`
        );
      }
      const elem = {};
      node[last].push(elem);
      const elemId = `${fullPath}[${node[last].length - 1}]`;
      pathShape.set(elemId, 'array_element');
      tableKeys.set(elemId, new Set());
      currentTableId = elemId;
      return elem;
    }

    // Plain [table] header.
    if (node[last] === undefined) {
      node[last] = {};
      pathShape.set(fullPath, 'table');
      declaredHeaders.add(fullPath);
      tableKeys.set(fullPath, new Set());
    } else if (Array.isArray(node[last])) {
      throw new Error(
        `duplicate or shape-mismatched table header at ${fullPath}: ` +
          `previously declared as array of tables ([[${fullPath}]]), cannot redeclare as table ([${fullPath}])`
      );
    } else if (typeof node[last] !== 'object') {
      throw new Error(`cannot redefine ${fullPath} as table`);
    } else if (declaredHeaders.has(fullPath)) {
      throw new Error(
        `duplicate or shape-mismatched table header at ${fullPath}: ` +
          `[${fullPath}] declared more than once`
      );
    } else {
      // Implicitly created earlier (e.g., as a parent path); first explicit
      // declaration is allowed.
      pathShape.set(fullPath, 'table');
      declaredHeaders.add(fullPath);
      if (!tableKeys.has(fullPath)) tableKeys.set(fullPath, new Set());
    }
    currentTableId = fullPath;
    return node[last];
  }

  for (let idx = 0; idx < records.length; idx += 1) {
    const rec = records[idx];
    if (rec.startsInMultilineString) continue;
    if (rec.tableHeader) {
      const segs = rec.tableHeader.segments;
      currentTable = walkPath(segs, { creatingArrayElement: rec.tableHeader.array });
      continue;
    }

    const trimmed = rec.text.trim();
    if (trimmed === '' || trimmed.startsWith('#')) continue;

    const equalsIndex = findTomlAssignmentEquals(rec.text);
    if (equalsIndex === -1) continue;

    const keyText = rec.text.slice(0, equalsIndex).trim();
    const segments = parseTomlKeyPath(keyText);
    if (!segments) {
      throw new Error(`invalid TOML key on line ${idx + 1}: ${rec.text}`);
    }

    // Value RHS may span multiple lines (inline arrays, multi-line strings,
    // inline tables). Parse from the absolute content offset right after `=`.
    const valueStartAbs = rec.start + equalsIndex + 1;
    const parsed = parseTomlValue(content, valueStartAbs);

    // #2760 CR4 finding 3 — verify the full RHS was consumed. Anything other
    // than whitespace + optional # comment between parsed.end and the next
    // newline (or EOF) means the parser silently accepted a prefix and
    // dropped trailing bytes. Reject so malformed TOML cannot slip past
    // "parse before commit" guarantees.
    let scan = parsed.end;
    while (scan < content.length && (content[scan] === ' ' || content[scan] === '\t')) {
      scan += 1;
    }
    if (scan < content.length && content[scan] !== '\n' && content[scan] !== '\r' && content[scan] !== '#') {
      const lineEnd = content.indexOf('\n', scan);
      const trailing = content.slice(scan, lineEnd === -1 ? content.length : lineEnd);
      throw new Error(
        `trailing bytes after value on line ${idx + 1}: ${JSON.stringify(trailing)}`
      );
    }

    // Place value into currentTable under dotted key.
    // #2760 CR5 finding 2 — reject duplicate keys per real TOML 1.0. Track
    // the dotted key against the current table instance id; an exact repeat
    // throws.
    let target = currentTable;
    for (let s = 0; s < segments.length - 1; s += 1) {
      const seg = segments[s];
      if (target[seg] === undefined) target[seg] = {};
      else if (typeof target[seg] !== 'object' || Array.isArray(target[seg])) {
        throw new Error(`cannot descend into non-table key ${seg}`);
      }
      target = target[seg];
    }
    const finalKey = segments[segments.length - 1];
    const dottedKey = segments.join('.');
    const keySet = ensureKeySet(currentTableId);
    if (keySet.has(dottedKey) || Object.prototype.hasOwnProperty.call(target, finalKey)) {
      throw new Error(
        `duplicate key ${dottedKey} in ${currentTableId === '__root__' ? 'root table' : currentTableId}`
      );
    }
    keySet.add(dottedKey);
    target[finalKey] = parsed.value;
  }

  return root;
}

/**
 * Validate that the post-install config.toml matches Codex's expected schema
 * (#2760, fix 3). Returns { ok: true } on success, or { ok: false, reason }
 * with a human-readable explanation of the offending section.
 *
 * Strategy: parse the bytes into a structured object first — malformed TOML
 * fails validation immediately rather than slipping past a header-only scan.
 * Then enforce the schema-shape rules against the parsed structure.
 *
 * Schema rules enforced:
 *   - File MUST parse as TOML (no syntax errors).
 *   - `agents` MUST be a struct table (`[agents.<name>]`) — never a bare
 *     table value or an array of tables.
 *   - `hooks.<Event>` MUST be an array of tables when present (Codex ≥0.124
 *     rejects bare `[hooks.<Event>]` single-bracket maps).
 */
function validateCodexConfigSchema(content) {
  let parsed;
  try {
    parsed = parseTomlToObject(content);
  } catch (e) {
    return {
      ok: false,
      reason: `TOML parse failed: ${e.message}`,
    };
  }

  // Header-shape check: arrays-of-tables are visible in the parsed structure
  // (as Array values) but bare-vs-struct distinction for `[agents]` requires
  // looking at section headers too — `[agents]` with `default = "x"` parses
  // to `{ agents: { default: 'x' } }`, indistinguishable from
  // `[agents.foo]` writing into the same shape. Use header sections to
  // disambiguate.
  const sections = getTomlTableSections(content);

  for (const section of sections) {
    if (section.array && section.path === 'agents') {
      return {
        ok: false,
        reason: '[[agents]] sequence form is invalid in current Codex schema (expected [agents.<name>] struct form)',
      };
    }

    if (!section.array && section.path === 'agents') {
      return {
        ok: false,
        reason: 'bare [agents] table is invalid in current Codex schema (expected [agents.<name>] struct form)',
      };
    }

    // hooks.state.* is Codex's persistent hook-trust namespace (added in
    // Codex CLI 0.130.0). It uses regular-table shape, NOT array-of-tables.
    // [[hooks.state]] or [[hooks.state.<key>]] (AoT) is invalid; reject it.
    if (section.array && (section.path === 'hooks.state' || section.path.startsWith('hooks.state.'))) {
      return {
        ok: false,
        reason: `[[${section.path}]] is invalid; hooks.state namespace must use regular tables`,
      };
    }

    // All other hooks.* paths (event handlers like hooks.SessionStart) require
    // AoT shape — bare [hooks.<Event>] (single-bracket) is invalid.
    if (!section.array && section.path.startsWith('hooks.') &&
        section.path !== 'hooks.state' && !section.path.startsWith('hooks.state.')) {
      return {
        ok: false,
        reason: `bare [${section.path}] table is invalid in current Codex schema (expected [[${section.path}]] array-of-tables)`,
      };
    }
  }

  // Structural confirmation against parsed object: any present hooks.<Event>
  // must be an array, and flat top-level [[hooks]] (parsed as Array on root)
  // is rejected — Codex 0.124.0+ requires [[hooks.<Event>]] namespaced form.
  if (parsed.hooks !== undefined) {
    if (Array.isArray(parsed.hooks)) {
      return {
        ok: false,
        reason: 'flat [[hooks]] array-of-tables is invalid in Codex 0.124.0+ (expected [[hooks.<Event>]] namespaced form)',
      };
    }
    if (typeof parsed.hooks === 'object' && parsed.hooks !== null) {
      for (const [event, value] of Object.entries(parsed.hooks)) {
        // hooks.state is Codex's persistent hook-trust namespace — a regular
        // object (table), not an array of event-handler tables.
        // Reject AoT shape (Array) and scalar forms; only plain objects are valid.
        if (event === 'state') {
          if (Array.isArray(value)) {
            return {
              ok: false,
              reason: `hooks.state must be a regular table/object, got array-of-tables`,
            };
          }
          if (typeof value !== 'object' || value === null) {
            return {
              ok: false,
              reason: `hooks.state must be a regular table/object, got ${typeof value}`,
            };
          }
          continue;
        }
        // Skip the nested .hooks sub-array — it lives under hooks.<Event>[n].hooks
        // and is validated separately below.
        if (!Array.isArray(value)) {
          return {
            ok: false,
            reason: `hooks.${event} must be an array of tables, got ${typeof value}`,
          };
        }
        // Each entry in hooks.<Event> must either be a matcher-only filter (no
        // handler fields) or carry a .hooks sub-array of handler tables.
        // Entries with handler fields (command, type, timeout, statusMessage) at
        // event-entry level but without a .hooks sub-table are the pre-#2773
        // single-block shape that Codex 0.124.0+ rejects. migrateCodexHooksMapFormat
        // converts these before validation runs; their presence here means migration
        // failed to cover this entry — fail loudly rather than pass a broken config.
        const HANDLER_FIELD_NAMES = new Set(['command', 'type', 'timeout', 'statusMessage']);
        for (const entry of value) {
          if (!entry || typeof entry !== 'object') continue;
          if (entry.hooks === undefined) {
            const strayKey = Object.keys(entry).find((k) => HANDLER_FIELD_NAMES.has(k));
            if (strayKey) {
              return {
                ok: false,
                reason: `hooks.${event}[] entry has handler field "${strayKey}" at event-entry level; ` +
                  `Codex 0.124.0+ requires handler fields nested under [[hooks.${event}.hooks]]`,
              };
            }
            continue;
          }
          if (!Array.isArray(entry.hooks)) {
            return {
              ok: false,
              reason: `hooks.${event}[].hooks must be an array of handler tables, got ${typeof entry.hooks}`,
            };
          }
          for (const handler of entry.hooks) {
            if (handler && typeof handler === 'object' && handler.type !== undefined) {
              if (handler.type !== 'command') {
                return {
                  ok: false,
                  reason: `hooks.${event}[].hooks[].type must be "command", got "${handler.type}"`,
                };
              }
            }
          }
        }
      }
    }
  }

  return { ok: true };
}

function normalizeCodexHooksLine(line, key) {
  const leadingWhitespace = line.match(/^\s*/)[0];
  const commentStart = findTomlCommentStart(line);
  const comment = commentStart === -1 ? '' : line.slice(commentStart);
  return `${leadingWhitespace}${key} = true${comment ? ` ${comment}` : ''}`;
}

function findTomlAssignmentBlockEnd(content, record) {
  const equalsIndex = findTomlAssignmentEquals(record.text);
  if (equalsIndex === -1) {
    return record.end + record.eol.length;
  }

  let i = record.start + equalsIndex + 1;
  let arrayDepth = 0;
  let inlineTableDepth = 0;

  while (i < content.length) {
    if (content.startsWith('\'\'\'', i)) {
      const closeIndex = content.indexOf('\'\'\'', i + 3);
      if (closeIndex === -1) {
        return content.length;
      }
      i = closeIndex + 3;
      continue;
    }

    if (content.startsWith('"""', i)) {
      const closeIndex = findMultilineBasicStringClose(content, i + 3);
      if (closeIndex === -1) {
        return content.length;
      }
      i = closeIndex + 3;
      continue;
    }

    const ch = content[i];

    if (ch === '\'') {
      i += 1;
      while (i < content.length) {
        if (content[i] === '\'') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    if (ch === '"') {
      i += 1;
      while (i < content.length) {
        if (content[i] === '\\') {
          i += 2;
          continue;
        }
        if (content[i] === '"') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }

    if (ch === '[') {
      arrayDepth += 1;
      i += 1;
      continue;
    }

    if (ch === ']') {
      if (arrayDepth > 0) {
        arrayDepth -= 1;
      }
      i += 1;
      continue;
    }

    if (ch === '{') {
      inlineTableDepth += 1;
      i += 1;
      continue;
    }

    if (ch === '}') {
      if (inlineTableDepth > 0) {
        inlineTableDepth -= 1;
      }
      i += 1;
      continue;
    }

    if (ch === '#') {
      while (i < content.length && content[i] !== '\n') {
        i += 1;
      }
      continue;
    }

    if (ch === '\n' && arrayDepth === 0 && inlineTableDepth === 0) {
      return i + 1;
    }

    i += 1;
  }

  return content.length;
}

function rewriteTomlKeyLines(content, matches, key) {
  if (matches.length === 0) {
    return content;
  }

  let rewritten = '';
  let cursor = 0;

  matches.forEach((match, index) => {
    rewritten += content.slice(cursor, match.start);
    if (index === 0) {
      const blockEnd = findTomlAssignmentBlockEnd(content, match);
      const blockEol = blockEnd > 0 && content[blockEnd - 1] === '\n'
        ? (blockEnd > 1 && content[blockEnd - 2] === '\r' ? '\r\n' : '\n')
        : '';
      // Preserve the existing key when one is present on the line
      // (`match.keyRaw`). This respects user ownership: a user-authored
      // `codex_hooks = true` line stays as `codex_hooks = true` even
      // though `hooks` is the canonical key in current Codex (#3566).
      // Codex's own `legacy_key` alias mechanism in codex-rs handles the
      // backward compat at the runtime layer. Migration to canonical is
      // a fresh-insert-only operation in ensureCodexHooksFeature.
      rewritten += normalizeCodexHooksLine(match.text, match.keyRaw || key) + blockEol;
      cursor = blockEnd;
      return;
    }
    cursor = findTomlAssignmentBlockEnd(content, match);
  });

  rewritten += content.slice(cursor);
  return rewritten;
}

/**
 * Atomic write — write to <target>.tmp-<pid>-<n> first, then renameSync over
 * the target. Eliminates the partial-write corruption window: an interrupted
 * write leaves the temp file (which we clean up) but never truncates the
 * original target. Used for any mutation of Codex config.toml so we cannot
 * leave the user with a half-written file (#2760 fix 4).
 *
 * Every temp path written is recorded in __atomicWrittenTmps so that
 * _cleanTmpFiles() can scope cleanup to files this installer process actually
 * created, avoiding accidental deletion of unrelated tools' temp files.
 */
let __atomicWriteCounter = 0;
// Set<string> — absolute paths of .tmp-<pid>-<n> files this process created.
const __atomicWrittenTmps = new Set();
function atomicWriteFileSync(target, data, options) {
  __atomicWriteCounter += 1;
  const tmp = `${target}.tmp-${process.pid}-${__atomicWriteCounter}`;
  __atomicWrittenTmps.add(tmp);
  try {
    fs.writeFileSync(tmp, data, options);
    fs.renameSync(tmp, target);
    // Successful rename: the tmp path no longer exists, but leave it in the
    // Set so _cleanTmpFiles can recognise it as installer-owned if it somehow
    // lingers (e.g. a rename succeeded but left a stale entry on some FS).
  } catch (e) {
    // Best-effort cleanup of the partial temp file; never mask the real error.
    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* ignore */ }
    throw e;
  }
}

/**
 * Merge GSD config block into an existing or new config.toml.
 * Three cases: new file, existing with GSD marker, existing without marker.
 *
 * All writes go through atomicWriteFileSync so a mid-write failure leaves
 * the original config.toml untouched (#2760 fix 4).
 */
function mergeCodexConfig(configPath, gsdBlock) {
  // Case 1: No config.toml — create fresh
  if (!fs.existsSync(configPath)) {
    atomicWriteFileSync(configPath, gsdBlock + '\n');
    return;
  }

  const existing = fs.readFileSync(configPath, 'utf8');
  const eol = detectLineEnding(existing);
  const normalizedGsdBlock = gsdBlock.replace(/\r?\n/g, eol);
  const markerIndex = existing.indexOf(GSD_CODEX_MARKER);

  // Case 2: Has GSD marker — truncate and re-append
  if (markerIndex !== -1) {
    let before = existing.substring(0, markerIndex).trimEnd();
    if (before) {
      // Strip any GSD-managed sections that leaked above the marker from previous installs
      before = stripLeakedGsdCodexSections(before).trimEnd();

      atomicWriteFileSync(configPath, before + eol + eol + normalizedGsdBlock + eol);
    } else {
      atomicWriteFileSync(configPath, normalizedGsdBlock + eol);
    }
    return;
  }

  // Case 3: No marker — append GSD block
  let content = stripLeakedGsdCodexSections(existing).trimEnd();
  if (content) {
    content = content + eol + eol + normalizedGsdBlock + eol;
  } else {
    content = normalizedGsdBlock + eol;
  }

  atomicWriteFileSync(configPath, content);
}

/**
 * Repair config.toml files corrupted by pre-#1346 GSD installs.
 * Non-boolean keys (e.g. model = "gpt-5.3-codex") that ended up under [features]
 * are relocated before the [features] header so Codex can parse them correctly.
 * Returns the content unchanged if no trapped keys are found.
 */
function repairTrappedFeaturesKeys(content) {
  const eol = detectLineEnding(content);
  const lineRecords = getTomlLineRecords(content);
  const featuresSection = getTomlTableSections(content)
    .find((section) => !section.array && section.path === 'features');

  if (!featuresSection) {
    return content;
  }

  // Find non-boolean key-value lines inside [features] that don't belong there.
  // Boolean keys (codex_hooks, multi_agent, etc.) are legitimate feature flags.
  const trappedLines = lineRecords.filter((record) => {
    if (record.tableHeader || record.startsInMultilineString) return false;
    if (record.tablePath !== 'features') return false;
    if (record.start < featuresSection.headerEnd) return false;
    if (record.end + record.eol.length > featuresSection.end) return false;
    if (!record.keySegments || record.keySegments.length === 0) return false;

    // Check if the value is a boolean — if so, it belongs under [features]
    const equalsIndex = findTomlAssignmentEquals(record.text);
    if (equalsIndex === -1) return false;
    const commentStart = findTomlCommentStart(record.text);
    const valueText = record.text
      .slice(equalsIndex + 1, commentStart === -1 ? record.text.length : commentStart)
      .trim();
    if (valueText === 'true' || valueText === 'false') return false;

    // Skip values that start a multiline string — they may legitimately live
    // under [features] and spanning multiple lines makes relocation unsafe.
    if (valueText.startsWith("'''") || valueText.startsWith('"""')) return false;

    // Non-boolean value — this key is trapped
    return true;
  });

  if (trappedLines.length === 0) {
    return content;
  }

  // Build the relocated text block from trapped lines
  const relocatedText = trappedLines.map((r) => r.text).join(eol) + eol;

  // Remove trapped lines from their current positions (with their EOLs)
  const removalRanges = trappedLines.map((r) => ({
    start: r.start,
    end: r.end + r.eol.length,
  }));
  let cleaned = removeContentRanges(content, removalRanges);

  // Collapse any runs of 3+ blank lines left behind
  cleaned = collapseTomlBlankLines(cleaned);

  // Re-locate the [features] header in the cleaned content
  const cleanedRecords = getTomlLineRecords(cleaned);
  const cleanedFeaturesHeader = cleanedRecords.find(
    (r) => r.tableHeader && r.tableHeader.path === 'features' && !r.tableHeader.array
  );

  if (!cleanedFeaturesHeader) {
    return cleaned;
  }

  // Insert relocated keys before [features]
  const before = cleaned.slice(0, cleanedFeaturesHeader.start);
  const after = cleaned.slice(cleanedFeaturesHeader.start);
  const needsGap = before.length > 0 && !before.endsWith(eol + eol);
  const trailingGap = after.length > 0 && !relocatedText.endsWith(eol + eol) ? eol : '';

  return before + (needsGap ? eol : '') + relocatedText + trailingGap + after;
}

function ensureCodexHooksFeature(configContent) {
  const eol = detectLineEnding(configContent);
  const lineRecords = getTomlLineRecords(configContent);

  const featuresSection = getTomlTableSections(configContent)
    .find((section) => !section.array && section.path === 'features');

  if (featuresSection) {
    const sectionLines = lineRecords
      .filter((record) =>
        !record.tableHeader &&
        !record.startsInMultilineString &&
        record.tablePath === 'features' &&
        record.start >= featuresSection.headerEnd &&
        record.end + record.eol.length <= featuresSection.end &&
        record.keySegments &&
        record.keySegments.length === 1 &&
        isCodexHooksFeatureKey(record.keySegments[0])
      );

    if (sectionLines.length > 0) {
      // Rewrite to canonical key — this migrates legacy `codex_hooks` to
      // `hooks` in-place on every reinstall. If the file already has the
      // canonical key the rewrite is a no-op shape-wise (same key, same
      // value). The rewriteTomlKeyLines helper preserves indentation,
      // trailing comments, and ownership-marker positioning, and always
      // emits the caller-supplied canonical key (#3566).
      const rewritten = rewriteTomlKeyLines(configContent, sectionLines, CODEX_HOOKS_FEATURE_KEY);
      return {
        content: repairTrappedFeaturesKeys(rewritten),
        ownership: null,
      };
    }

    const sectionBody = configContent.slice(featuresSection.headerEnd, featuresSection.end);
    const needsSeparator = sectionBody.length > 0 && !sectionBody.endsWith('\n') && !sectionBody.endsWith('\r\n');
    const insertPrefix = sectionBody.length === 0 && featuresSection.headerEnd === configContent.length ? eol : '';
    const insertText = `${insertPrefix}${needsSeparator ? eol : ''}${CODEX_HOOKS_FEATURE_KEY} = true${eol}`;
    const merged = configContent.slice(0, featuresSection.end) + insertText + configContent.slice(featuresSection.end);
    return {
      content: repairTrappedFeaturesKeys(merged),
      ownership: 'section',
    };
  }

  const rootFeatureLines = lineRecords
    .filter((record) =>
      !record.tableHeader &&
      !record.startsInMultilineString &&
      record.tablePath === null &&
      record.keySegments &&
      record.keySegments[0] === 'features'
    );

  const rootCodexHooksLines = rootFeatureLines
    .filter((record) => record.keySegments.length === 2 && isCodexHooksFeatureKey(record.keySegments[1]));

  if (rootCodexHooksLines.length > 0) {
    return {
      content: rewriteTomlKeyLines(configContent, rootCodexHooksLines, `features.${CODEX_HOOKS_FEATURE_KEY}`),
      ownership: null,
    };
  }

  const rootFeaturesValueLines = rootFeatureLines
    .filter((record) => record.keySegments.length === 1);

  if (rootFeaturesValueLines.length > 0) {
    return { content: configContent, ownership: null };
  }

  if (rootFeatureLines.length > 0) {
    const lastFeatureLine = rootFeatureLines[rootFeatureLines.length - 1];
    const insertAt = findTomlAssignmentBlockEnd(configContent, lastFeatureLine);
    const prefix = insertAt > 0 && configContent[insertAt - 1] === '\n' ? '' : eol;
    return {
      content: configContent.slice(0, insertAt) +
        `${prefix}features.${CODEX_HOOKS_FEATURE_KEY} = true${eol}` +
        configContent.slice(insertAt),
      ownership: 'root_dotted',
    };
  }

  const featuresBlock = `[features]${eol}${CODEX_HOOKS_FEATURE_KEY} = true${eol}`;
  if (!configContent) {
    return { content: featuresBlock, ownership: 'section' };
  }
  // Insert [features] before the first table header, preserving bare top-level keys.
  // Prepending would trap them under [features] where Codex expects only booleans (#1202).
  const firstTableHeader = lineRecords.find(r => r.tableHeader);
  if (firstTableHeader) {
    const before = configContent.slice(0, firstTableHeader.start);
    const after = configContent.slice(firstTableHeader.start);
    const needsGap = before.length > 0 && !before.endsWith(eol + eol);
    return {
      content: before + (needsGap ? eol : '') + featuresBlock + eol + after,
      ownership: 'section',
    };
  }
  // No table headers — append [features] after top-level keys
  const needsGap = configContent.length > 0 && !configContent.endsWith(eol + eol);
  return { content: configContent + (needsGap ? eol : '') + featuresBlock, ownership: 'section' };
}

function hasEnabledCodexHooksFeature(configContent) {
  const lineRecords = getTomlLineRecords(configContent);

  return lineRecords.some((record) => {
    if (record.tableHeader || record.startsInMultilineString || !record.keySegments) {
      return false;
    }

    const isSectionKey = record.tablePath === 'features' &&
      record.keySegments.length === 1 &&
      isCodexHooksFeatureKey(record.keySegments[0]);
    const isRootDottedKey = record.tablePath === null &&
      record.keySegments.length === 2 &&
      record.keySegments[0] === 'features' &&
      isCodexHooksFeatureKey(record.keySegments[1]);

    if (!isSectionKey && !isRootDottedKey) {
      return false;
    }

    const equalsIndex = findTomlAssignmentEquals(record.text);
    if (equalsIndex === -1) {
      return false;
    }

    const commentStart = findTomlCommentStart(record.text);
    const valueText = record.text.slice(equalsIndex + 1, commentStart === -1 ? record.text.length : commentStart).trim();
    return valueText === 'true';
  });
}

/**
 * Merge GSD instructions into copilot-instructions.md.
 * Three cases: new file, existing with markers, existing without markers.
 * @param {string} filePath - Full path to copilot-instructions.md
 * @param {string} gsdContent - Template content (without markers)
 */
function mergeCopilotInstructions(filePath, gsdContent) {
  const gsdBlock = GSD_COPILOT_INSTRUCTIONS_MARKER + '\n' +
    gsdContent.trim() + '\n' +
    GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER;

  // Case 1: No file — create fresh
  if (!fs.existsSync(filePath)) {
    fs.writeFileSync(filePath, gsdBlock + '\n');
    return;
  }

  const existing = fs.readFileSync(filePath, 'utf8');
  const openIndex = existing.indexOf(GSD_COPILOT_INSTRUCTIONS_MARKER);
  const closeIndex = existing.indexOf(GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER);

  // Case 2: Has GSD markers — replace between markers
  if (openIndex !== -1 && closeIndex !== -1) {
    const before = existing.substring(0, openIndex).trimEnd();
    const after = existing.substring(closeIndex + GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER.length).trimStart();
    let newContent = '';
    if (before) newContent += before + '\n\n';
    newContent += gsdBlock;
    if (after) newContent += '\n\n' + after;
    newContent += '\n';
    fs.writeFileSync(filePath, newContent);
    return;
  }

  // Case 3: No markers — append at end
  const content = existing.trimEnd() + '\n\n' + gsdBlock + '\n';
  fs.writeFileSync(filePath, content);
}

/**
 * Strip GSD section from copilot-instructions.md content.
 * Returns cleaned content, or null if file should be deleted (was GSD-only).
 * @param {string} content - File content
 * @returns {string|null} - Cleaned content or null if empty
 */
function stripGsdFromCopilotInstructions(content) {
  const openIndex = content.indexOf(GSD_COPILOT_INSTRUCTIONS_MARKER);
  const closeIndex = content.indexOf(GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER);

  if (openIndex !== -1 && closeIndex !== -1) {
    const before = content.substring(0, openIndex).trimEnd();
    const after = content.substring(closeIndex + GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER.length).trimStart();
    const cleaned = (before + (before && after ? '\n\n' : '') + after).trim();
    if (!cleaned) return null;
    return cleaned + '\n';
  }

  // No markers found — nothing to strip
  return content;
}

// ── Cline directory-form rules + hooks + AGENTS.md (issue #787) ────────────────
//
// Cline v3.36 added a hooks system and a `.clinerules/` directory form. Because
// `.clinerules` cannot be both a file AND a directory, emitting hooks under
// `.clinerules/hooks/` requires migrating the rules content into the directory
// form (`.clinerules/gsd.md`). Sources adjudicated:
//   - https://cline.bot/blog/cline-v3-36-hooks
//   - https://docs.cline.bot/customization/cline-rules

const GSD_AGENTS_MD_MARKER = '<!-- GSD Configuration — managed by gsd-core installer -->';
const GSD_AGENTS_MD_CLOSE_MARKER = '<!-- End GSD Configuration -->';

/**
 * The GSD instruction body shared by the Cline directory-form rules file and
 * the cross-tool AGENTS.md block. Self-contained — references only the gsd-core
 * engine layout, not the (separate) #782 Cline skills directory.
 */
function buildClineRulesBody() {
  return [
    '# GSD Core — Git. Ship. Done.',
    '',
    '- GSD workflows live in `gsd-core/workflows/`. Load the relevant workflow when',
    '  the user runs a `/gsd-*` command.',
    '- GSD agents live in `agents/`. Use the matching agent when spawning subagents.',
    '- GSD tools are at `gsd-core/bin/gsd-tools.cjs`. Run with `node`.',
    '- Planning artifacts live in `.planning/`. Never edit them outside a GSD workflow.',
    '- Do not apply GSD workflows unless the user explicitly asks for them.',
    '- When a GSD command triggers a deliverable (feature, fix, docs), offer the next',
    '  step to the user using Cline\'s ask_user tool after completing it.',
  ].join('\n') + '\n';
}

/** AGENTS.md body for the cross-tool global instruction target (`~/.agents/AGENTS.md`). */
function buildClineAgentsMdBody() {
  return buildClineRulesBody();
}

/**
 * The Cline PreToolUse hook script (issue #787).
 *
 * Cline invokes hooks as executable scripts named exactly after the event with
 * no extension, passing the operation context as JSON on stdin and reading a
 * JSON decision from stdout ({ cancel, errorMessage, contextModification }).
 *
 * This hook is a self-standing planning-artifact guard: it cancels write-class
 * tool calls that target `.planning/` (GSD-owned artifacts), and otherwise
 * allows the operation. It FAILS OPEN — any parse/IO error allows the call so a
 * hook bug can never wedge the user. No dependency on the #782 skills work.
 */
function buildClinePreToolUseHook() {
  return `#!/usr/bin/env node
'use strict';
/* GSD-managed Cline PreToolUse hook — gsd-core issue #787.
 * Protocol: JSON on stdin -> JSON decision on stdout.
 * Honored fields: { cancel, errorMessage, contextModification }.
 * Fails open: any error allows the operation. */
let raw = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (c) => { raw += c; });
process.stdin.on('end', () => {
  const allow = () => process.stdout.write(JSON.stringify({ cancel: false }));
  let input;
  try { input = JSON.parse(raw || '{}'); } catch { return allow(); }
  try {
    const tool = String(
      input.toolName || input.tool_name || input.tool ||
      (input.toolInput && input.toolInput.name) || (input.tool_input && input.tool_input.name) || ''
    ).toLowerCase();
    const isWrite = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/.test(tool);
    // Collect only PATH-bearing field values (not free-form content), so a doc
    // that merely mentions ".planning/" in its body is never falsely blocked.
    const paths = [];
    const PATH_KEY = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
    const walk = (v, depth) => {
      if (depth > 5 || paths.length > 64) return;
      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
      if (v && typeof v === 'object') {
        for (const k of Object.keys(v)) {
          const val = v[k];
          if (typeof val === 'string' && PATH_KEY.test(k)) paths.push(val);
          else walk(val, depth + 1);
        }
      }
    };
    walk(input, 0);
    const isPlanningPath = (s) => /(^|[\\\\/])\\.planning([\\\\/]|$)/.test(s);
    if (isWrite && paths.some(isPlanningPath)) {
      return process.stdout.write(JSON.stringify({
        cancel: true,
        errorMessage:
          'GSD: .planning/ artifacts are managed by GSD workflows. Edit them only through a /gsd-* command, not directly.',
      }));
    }
  } catch { /* fall through to allow */ }
  return allow();
});
`;
}

/**
 * Merge the GSD AGENTS.md block into an existing file (or create it), preserving
 * any user content. Mirrors mergeCopilotInstructions: marker-delimited, idempotent.
 */
function mergeGsdAgentsMd(filePath, gsdContent) {
  const gsdBlock = GSD_AGENTS_MD_MARKER + '\n' + gsdContent.trim() + '\n' + GSD_AGENTS_MD_CLOSE_MARKER;

  if (!fs.existsSync(filePath)) {
    fs.mkdirSync(path.dirname(filePath), { recursive: true });
    fs.writeFileSync(filePath, gsdBlock + '\n');
    return;
  }

  const existing = fs.readFileSync(filePath, 'utf8');
  const openIndex = existing.indexOf(GSD_AGENTS_MD_MARKER);
  const closeIndex = existing.indexOf(GSD_AGENTS_MD_CLOSE_MARKER);

  if (openIndex !== -1 && closeIndex !== -1) {
    const before = existing.substring(0, openIndex).trimEnd();
    const after = existing.substring(closeIndex + GSD_AGENTS_MD_CLOSE_MARKER.length).trimStart();
    let newContent = '';
    if (before) newContent += before + '\n\n';
    newContent += gsdBlock;
    if (after) newContent += '\n\n' + after;
    newContent += '\n';
    fs.writeFileSync(filePath, newContent);
    return;
  }

  fs.writeFileSync(filePath, existing.trimEnd() + '\n\n' + gsdBlock + '\n');
}

/**
 * Strip the GSD block from AGENTS.md content. Returns null if the file became
 * empty (was GSD-only), the unchanged content if no markers were found, or the
 * cleaned content otherwise.
 */
function stripGsdFromAgentsMd(content) {
  const openIndex = content.indexOf(GSD_AGENTS_MD_MARKER);
  const closeIndex = content.indexOf(GSD_AGENTS_MD_CLOSE_MARKER);
  if (openIndex !== -1 && closeIndex !== -1) {
    const before = content.substring(0, openIndex).trimEnd();
    const after = content.substring(closeIndex + GSD_AGENTS_MD_CLOSE_MARKER.length).trimStart();
    const cleaned = (before + (before && after ? '\n\n' : '') + after).trim();
    if (!cleaned) return null;
    return cleaned + '\n';
  }
  return content;
}

/**
 * Write the full Cline runtime artifact set (directory-form rules + PreToolUse
 * hook) into targetDir, migrating a legacy single-file `.clinerules` if present.
 * For global installs, also merge the cross-tool ~/.agents/AGENTS.md target.
 *
 * Returns the list of manifest-relative paths written under targetDir (so the
 * caller can hash-track them).
 */
function writeClineArtifacts(targetDir, isGlobalInstall) {
  const written = [];
  const clinerulesDir = path.join(targetDir, '.clinerules');

  // Migrate a pre-#787 single-file `.clinerules` — a path cannot be both a
  // file and a directory, so the legacy file must be removed first. The legacy
  // file is GSD-authored (the installer wrote its full contents with no user
  // merge surface), so replacing it with the newer directory form is the
  // intended upgrade. Use lstat so a symlink is unlinked in place rather than
  // followed (which would write GSD files through the link into an external dir).
  try {
    if (fs.existsSync(clinerulesDir)) {
      const st = fs.lstatSync(clinerulesDir);
      if (st.isFile() || st.isSymbolicLink()) {
        fs.unlinkSync(clinerulesDir);
        console.log(`  ${green}✓${reset} Migrated legacy .clinerules to directory form`);
      }
    }
  } catch { /* best-effort migration */ }

  fs.mkdirSync(clinerulesDir, { recursive: true });
  fs.writeFileSync(path.join(clinerulesDir, 'gsd.md'), buildClineRulesBody());
  written.push('.clinerules/gsd.md');
  console.log(`  ${green}✓${reset} Wrote .clinerules/gsd.md`);

  const hooksDir = path.join(clinerulesDir, 'hooks');
  fs.mkdirSync(hooksDir, { recursive: true });
  const hookPath = path.join(hooksDir, 'PreToolUse');
  fs.writeFileSync(hookPath, buildClinePreToolUseHook());
  try { fs.chmodSync(hookPath, 0o755); } catch { /* Windows: hooks unsupported anyway */ }
  written.push('.clinerules/hooks/PreToolUse');
  console.log(`  ${green}✓${reset} Wrote .clinerules/hooks/PreToolUse`);

  // Global cross-tool instruction target. Cline reads ~/.agents/AGENTS.md
  // (docs.cline.bot/customization/cline-rules). Merge-safe so we never clobber
  // a user's or another tool's AGENTS.md. Tracked via markers (like copilot),
  // not the per-configDir manifest, since it lives outside configDir.
  if (isGlobalInstall) {
    try {
      const agentsPath = path.join(os.homedir(), '.agents', 'AGENTS.md');
      mergeGsdAgentsMd(agentsPath, buildClineAgentsMdBody());
      console.log(`  ${green}✓${reset} Merged GSD instructions into ~/.agents/AGENTS.md`);
    } catch (err) {
      console.warn(`  ${yellow}⚠${reset} Could not write ~/.agents/AGENTS.md: ${err.message}`);
    }
  }

  return written;
}

// ── Cursor hooks.json reconciler (issue #777) ────────────────────────────────
//
// Cursor v2.4+ supports a hooks.json lifecycle hook system. GSD registers two
// managed command hooks:
//   sessionStart → gsd-cursor-session-start.js  (context injection)
//   postToolUse  → gsd-cursor-post-tool.js       (STATE.md update monitor)
//
// hooks.json schema:
//   { "version": 1, "hooks": { "<event>": [ { "type": "command", "command": "<path>" } ] } }
//
// Location:
//   Global:  ~/.cursor/hooks.json
//   Local:   <project-root>/.cursor/hooks.json
//
// GSD entries are identified by a top-level `"gsd-managed": true` field on
// each hook entry. Non-GSD entries are preserved. The reconciler is idempotent
// (safe to re-run) and preserves user-owned entries in the file.
//
// References: https://cursor.com/docs/hooks

/**
 * Build a managed Cursor hook entry for a given hook script path.
 *
 * @param {string} scriptPath - Absolute path to the hook script
 * @returns {object} Cursor hook entry object
 */
function buildCursorHookEntry(scriptPath) {
  return {
    type: 'command',
    command: scriptPath.replace(/\\/g, '/'),
    [GSD_CURSOR_HOOK_MARKER]: true,
  };
}

/**
 * Return true if a Cursor hook entry is GSD-managed.
 * Detection: presence of the GSD_CURSOR_HOOK_MARKER sentinel field.
 *
 * @param {object} entry - A hooks array element from hooks.json
 * @returns {boolean}
 */
function isManagedCursorHookEntry(entry) {
  return Boolean(entry && typeof entry === 'object' && entry[GSD_CURSOR_HOOK_MARKER]);
}

/**
 * Reconcile the GSD-managed entries in a Cursor hooks.json file.
 *
 * Supports both known hooks.json shapes:
 *   1) { "version": 1, "hooks": { "sessionStart": [...], "postToolUse": [...] } }
 *   2) { "sessionStart": [...], "postToolUse": [...] }   (no wrapper object)
 *
 * Managed entries (those with GSD_CURSOR_HOOK_MARKER) are removed then
 * re-added if managedEntries is non-null/non-empty. User-owned entries are
 * preserved. File is written atomically only when content changes.
 *
 * @param {string} hooksJsonPath - Absolute path to the hooks.json file
 * @param {{ sessionStart?: object|null, postToolUse?: object|null }|null} managedEntries
 *   Map from event name to the new hook entry to register (or null to remove).
 *   Pass null for the whole param to remove all managed entries.
 * @returns {{ changed: boolean, wrote: boolean, path: string }}
 */
function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
  let parsed = {};
  let currentContent = null;

  if (fs.existsSync(hooksJsonPath)) {
    const raw = fs.readFileSync(hooksJsonPath, 'utf8');
    currentContent = raw;
    if (raw.trim()) {
      try {
        parsed = JSON.parse(raw);
      } catch (err) {
        throw new Error(`Cursor hooks.json parse failed: ${err && err.message ? err.message : String(err)}`);
      }
    }
  }
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};

  // Cursor's canonical hooks.json schema is { "version": 1, "hooks": { ... } }.
  // GSD always writes (and migrates to) the nested shape so Cursor reads it correctly.
  // The flat shape { "sessionStart": [...] } is accepted on read for backwards compat
  // with manually-written files, but the output always uses the nested form.
  const hasNestedHooksObject =
    parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks);
  if (!hasNestedHooksObject) {
    // Migrate flat shape (or empty {}) to nested: lift event keys into hooks:{}.
    const eventKeys = ['sessionStart', 'postToolUse'];
    const lifted = {};
    for (const k of eventKeys) {
      if (Array.isArray(parsed[k])) {
        lifted[k] = parsed[k];
        delete parsed[k];
      }
    }
    parsed.hooks = lifted;
  }
  if (!parsed.version) parsed.version = 1;
  const hookTable = parsed.hooks;

  // Events GSD manages.
  const MANAGED_EVENTS = ['sessionStart', 'postToolUse'];
  const entries = managedEntries || {};

  for (const event of MANAGED_EVENTS) {
    const existing = Array.isArray(hookTable[event]) ? hookTable[event] : [];
    // Strip all prior GSD-managed entries for this event.
    const userOwned = existing.filter((e) => !isManagedCursorHookEntry(e));
    const newEntry = entries[event] || null;
    if (newEntry) {
      hookTable[event] = [...userOwned, newEntry];
    } else {
      // Remove-only: keep user entries, or delete the key if it would be empty.
      if (userOwned.length > 0) {
        hookTable[event] = userOwned;
      } else {
        delete hookTable[event];
      }
    }
  }

  // hookTable is parsed.hooks (always nested now); no reassignment needed.
  // Write only if content changed or if we're creating the file for the first time.
  const nextContent = `${JSON.stringify(parsed, null, 2)}\n`;
  const changed = currentContent !== nextContent;
  const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
  if (shouldWrite) {
    atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
  }

  return { changed: changed, wrote: shouldWrite, path: hooksJsonPath };
}

/**
 * #777 — Write GSD-managed Cursor lifecycle hooks into <targetDir>/hooks.json.
 *
 * Both managed hook scripts (gsd-cursor-session-start.js, gsd-cursor-post-tool.js)
 * are copied from the GSD hooks/ source to <targetDir>/hooks/ first, so the
 * hooks.json entries never reference a script that wasn't installed.
 *
 * @param {string} targetDir - The Cursor config dir (global: ~/.cursor; local: .cursor)
 * @param {string} src       - The GSD install source root (for copying hook scripts)
 * @param {{ absoluteRunner?: string|null }} opts
 * @returns {{ hooksJsonPath: string, changed: boolean }}
 */
function writeCursorHooksJson(targetDir, src, opts) {
  opts = opts || {};
  const hooksDir = path.join(targetDir, 'hooks');
  fs.mkdirSync(hooksDir, { recursive: true });

  // Copy the two GSD-managed hook scripts from the GSD source hooks/ directory.
  // Apply the same /gsd:/gi → gsd- rewrite used by copyWithPathReplacement for Cursor
  // JS files, so the installed hook scripts contain no /gsd: colon refs (bug-376 2b).
  // Track which scripts were successfully installed so we never register a hook entry
  // that references a script that wasn't copied (dangling command guard).
  const hookScripts = [GSD_CURSOR_SESSION_HOOK_SCRIPT, GSD_CURSOR_POST_TOOL_HOOK_SCRIPT];
  const srcHooksDir = path.join(src, 'hooks');
  const installedScripts = new Set();
  for (const script of hookScripts) {
    const srcPath = path.join(srcHooksDir, script);
    const destPath = path.join(hooksDir, script);
    if (fs.existsSync(srcPath)) {
      let content = fs.readFileSync(srcPath, 'utf8');
      // Rewrite /gsd:<cmd> → gsd-<cmd> so installed hook scripts are consistent
      // with the Cursor convention (no colon-form slash commands in agent context).
      content = content.replace(/gsd:/gi, 'gsd-');
      fs.writeFileSync(destPath, content);
      try { fs.chmodSync(destPath, 0o755); } catch { /* Windows: ignore chmod */ }
      installedScripts.add(script);
    }
  }

  // Build command strings using the same buildHookCommand helper used by other runtimes.
  // buildHookCommand resolves the node runner + emits "<runner>" "<targetDir>/hooks/<name>".
  const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
  // buildHookCommand('gsd-cursor-session-start.js', ...): sessionStart → context injection
  // Only register the hook entry if the script was actually installed (dangling guard).
  const sessionStartCmd = installedScripts.has('gsd-cursor-session-start.js')
    ? buildHookCommand(targetDir, 'gsd-cursor-session-start.js', hookOpts)
    : null;
  // buildHookCommand('gsd-cursor-post-tool.js', ...): postToolUse → STATE.md update monitor
  const postToolCmd = installedScripts.has('gsd-cursor-post-tool.js')
    ? buildHookCommand(targetDir, 'gsd-cursor-post-tool.js', hookOpts)
    : null;

  // Build managed entries; skip events whose command couldn't be resolved (e.g. no node).
  const managedEntries = {};
  if (sessionStartCmd) {
    managedEntries.sessionStart = {
      type: 'command',
      command: sessionStartCmd,
      [GSD_CURSOR_HOOK_MARKER]: true,
    };
  }
  if (postToolCmd) {
    managedEntries.postToolUse = {
      type: 'command',
      command: postToolCmd,
      [GSD_CURSOR_HOOK_MARKER]: true,
    };
  }

  const hooksJsonPath = path.join(targetDir, 'hooks.json');
  const result = reconcileCursorHooksJson(hooksJsonPath, managedEntries);
  return { hooksJsonPath, changed: result.changed };
}

/**
 * Remove all GSD-managed Cursor lifecycle hook entries from hooks.json.
 * User-owned entries are preserved. If the file becomes empty, it is removed.
 *
 * @param {string} targetDir - The Cursor config dir
 * @returns {{ changed: boolean }}
 */
function removeCursorHooksJson(targetDir) {
  const hooksJsonPath = path.join(targetDir, 'hooks.json');
  if (!fs.existsSync(hooksJsonPath)) return { changed: false };
  const result = reconcileCursorHooksJson(hooksJsonPath, null);
  // If the resulting file has no meaningful hook content, remove it.
  // A file is "empty" if it contains only the scaffolding (version, empty hooks
  // object, or a bare {}) with no user-authored hook entries.
  if (result.changed) {
    try {
      const contentRaw = fs.readFileSync(hooksJsonPath, 'utf8');
      const parsed = JSON.parse(contentRaw);
      // reconcileCursorHooksJson always writes the nested { version, hooks:{} } shape.
      // The file is "empty" when there are no remaining hook events with entries.
      const hookTable = (parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks))
        ? parsed.hooks
        : {};
      const hasAnyEvents = Object.keys(hookTable).some(
        (k) => Array.isArray(hookTable[k]) && hookTable[k].length > 0,
      );
      if (!hasAnyEvents) {
        fs.unlinkSync(hooksJsonPath);
        return { changed: true };
      }
    } catch { /* best-effort: leave the file */ }
  }
  return { changed: result.changed };
}

/**
 * #786 — Build the GSD-managed GitHub Copilot lifecycle hook config object.
 *
 * Returns the verbatim JSON shape Copilot CLI expects:
 *   { version: 1, hooks: { sessionStart: [ <hook entry> ] } }
 *
 * The sessionStart entry is a `command` hook whose `bash`/`powershell` bodies
 * run inline (no external script file), so the config can never reference a
 * hook script that the installer did not also install — it is self-contained
 * by construction. The command is advisory-only (always exits 0) and orients
 * the agent toward the project's GSD planning state at session start.
 *
 * @returns {object} Copilot hooks-configuration object
 */
function buildCopilotHookConfig() {
  return {
    version: 1,
    hooks: {
      sessionStart: [
        {
          type: 'command',
          bash: GSD_COPILOT_SESSION_HOOK_BASH,
          powershell: GSD_COPILOT_SESSION_HOOK_PWSH,
          timeoutSec: 10,
        },
      ],
    },
  };
}

/**
 * #786 — Write the GSD-managed Copilot lifecycle hook config under the runtime
 * config dir (`<targetDir>/hooks/gsd-session.json`). For local installs
 * targetDir is `.github` (→ `.github/hooks/`); for global installs it is
 * `~/.copilot` (→ `~/.copilot/hooks/`) — both are valid Copilot hook locations.
 *
 * The managed file is fully owned by GSD, so it is overwritten wholesale on
 * every install (idempotent). User-authored sibling `*.json` hook files in the
 * same directory are untouched.
 *
 * @param {string} targetDir - The Copilot config dir
 * @returns {string} The path the hook config was written to
 */
function writeCopilotHookConfig(targetDir) {
  const hooksDir = path.join(targetDir, 'hooks');
  fs.mkdirSync(hooksDir, { recursive: true });
  const hookPath = path.join(hooksDir, GSD_COPILOT_HOOK_FILE);
  fs.writeFileSync(hookPath, JSON.stringify(buildCopilotHookConfig(), null, 2) + '\n');
  return hookPath;
}

/**
 * Generate config.toml and per-agent .toml files for Codex.
 * Reads agent .md files from source, extracts metadata, writes .toml configs.
 */
function installCodexConfig(targetDir, agentsSrc) {
  const configPath = path.join(targetDir, 'config.toml');
  const agentsTomlDir = path.join(targetDir, 'agents');
  fs.mkdirSync(agentsTomlDir, { recursive: true });

  const agentEntries = fs.readdirSync(agentsSrc).filter(f => f.startsWith('gsd-') && f.endsWith('.md'));
  const agents = [];

  // Compute the Codex GSD install path (absolute, so subagents with empty $HOME work — #820)
  const codexGsdPath = `${path.resolve(targetDir, 'gsd-core').replace(/\\/g, '/')}/`;

  for (const file of agentEntries) {
    let content = fs.readFileSync(path.join(agentsSrc, file), 'utf8');
    // Replace full .claude/gsd-core prefix so path resolves to the Codex
    // GSD install before generic .claude → .codex conversion rewrites it.
    content = content.replace(/~\/\.claude\/gsd-core\//g, codexGsdPath);
    content = content.replace(/\$HOME\/\.claude\/gsd-core\//g, codexGsdPath);
    // Route TOML emit through the same full Claude→Codex conversion pipeline
    // used on the `.md` emit path (#2639). Covers: slash-command rewrites,
    // $ARGUMENTS → {{GSD_ARGS}}, /clear removal, anchored and bare .claude/
    // paths, .claudeignore → .codexignore, and standalone "Claude" /
    // CLAUDE.md neutralization via neutralizeAgentReferences(..., 'AGENTS.md').
    content = convertClaudeToCodexMarkdown(content);
    const { frontmatter } = extractFrontmatterAndBody(content);
    const name = extractFrontmatterField(frontmatter, 'name') || file.replace('.md', '');
    const description = extractFrontmatterField(frontmatter, 'description') || '';

    agents.push({ name, description: toSingleLine(description) });

    // Pass model overrides from both per-project `.planning/config.json` and
    // `~/.gsd/defaults.json` (project wins on conflict) so Codex TOML files
    // embed the configured model — Codex cannot receive model inline (#2256).
    // Previously only the global file was read, which silently dropped the
    // per-project override the reporter had set for gsd-codebase-mapper.
    // #2517 — also pass the runtime-aware tier resolver so profile tiers can
    // resolve to Codex-native model IDs + reasoning_effort when `runtime: "codex"`
    // is set in defaults.json.
    const modelOverrides = readGsdEffectiveModelOverrides(targetDir);
    // Pass `targetDir` so per-project .planning/config.json wins over global
    // ~/.gsd/defaults.json — without this, the PR's headline claim that
    // setting runtime in the project config reaches the Codex emit path is
    // false (review finding #1).
    const runtimeResolver = readGsdRuntimeProfileResolver(targetDir);
    // #443 — pass unified effort config so model_reasoning_effort in the .toml
    // follows the same config-driven precedence as the Claude .md effort key.
    const effortCfg = readGsdEffectiveEffortConfig(targetDir);
    const tomlContent = generateCodexAgentToml(name, content, modelOverrides, runtimeResolver, effortCfg);
    fs.writeFileSync(path.join(agentsTomlDir, `${name}.toml`), tomlContent);
  }

  const gsdBlock = generateCodexConfigBlock(agents, targetDir);
  mergeCodexConfig(configPath, gsdBlock);

  return agents.length;
}

/**
 * Strip HTML <sub> tags for Gemini CLI output
 * Terminals don't support subscript — Gemini renders these as raw HTML.
 * Converts <sub>text</sub> to italic *(text)* for readable terminal output.
 */
/**
 * Runtime-neutral agent name and instruction file replacement.
 * Used by ALL non-Claude runtime converters to avoid Claude-specific
 * references in workflow prompts, agent definitions, and documentation.
 *
 * Replaces:
 * - Standalone "Claude" (agent name) → "the agent"
 *   Preserves: "Claude Code" (product), "Claude Opus/Sonnet/Haiku" (models),
 *   "claude-" (prefixes), "CLAUDE.md" (handled separately)
 * - "CLAUDE.md" → runtime-appropriate instruction file
 * - "Do NOT load full AGENTS.md" → removed (harmful for AGENTS.md runtimes)
 *
 * @param {string} content - File content to neutralize
 * @param {string} instructionFile - Runtime's instruction file ('AGENTS.md', 'GEMINI.md', etc.)
 * @returns {string} Content with runtime-neutral references
 */
function neutralizeAgentReferences(content, instructionFile) {
  let c = content;
  // Replace standalone "Claude" (the agent) but preserve product/model names.
  // Negative lookahead avoids: Claude Code, Claude Opus/Sonnet/Haiku, Claude native, Claude-based
  c = c.replace(/\bClaude(?! Code| Opus| Sonnet| Haiku| native| based|-)\b(?!\.md)/g, 'the agent');
  // Replace CLAUDE.md with runtime-appropriate instruction file
  if (instructionFile) {
    c = c.replace(/CLAUDE\.md/g, instructionFile);
  }
  // Remove instructions that conflict with AGENTS.md-based runtimes
  c = c.replace(/Do NOT load full `AGENTS\.md` files[^\n]*/g, '');
  return c;
}

function stripSubTags(content) {
  return content.replace(/<sub>(.*?)<\/sub>/g, '*($1)*');
}

/**
 * Convert Claude Code agent frontmatter to Gemini CLI format
 * Gemini agents use .md files with YAML frontmatter, same as Claude,
 * but with different field names and formats:
 * - tools: must be a YAML array (not comma-separated string)
 * - tool names: must use Gemini built-in names (read_file, not Read)
 * - color: must be removed (causes validation error)
 * - skills: must be removed (causes validation error)
 * - mcp__* tools: must be excluded (auto-discovered at runtime)
 */
let _gsdCommandRoster = null;
let _gsdCommandRosterWarned = false;

/**
 * Get the list of known GSD commands from the source directory.
 * Caches the result after the first scan. Emits a one-shot warning if the
 * source directory cannot be located — an empty roster silently neutralises
 * every Gemini slash-command conversion, which is the bug this code exists
 * to prevent. The warning is gated on GSD_TEST_MODE to keep test output clean.
 * @returns {Set<string>} Set of command names (without .md extension)
 */
function getGsdCommandRoster() {
  if (_gsdCommandRoster) return _gsdCommandRoster;
  const baseDir = (typeof __dirname !== 'undefined') ? __dirname : process.cwd();
  const gsdSrc = path.join(baseDir, '..', 'commands', 'gsd');
  if (fs.existsSync(gsdSrc)) {
    _gsdCommandRoster = new Set(
      fs.readdirSync(gsdSrc)
        .filter(f => f.endsWith('.md'))
        .map(f => f.replace('.md', ''))
    );
  } else {
    _gsdCommandRoster = new Set();
    if (!_gsdCommandRosterWarned && !process.env.GSD_TEST_MODE) {
      _gsdCommandRosterWarned = true;
      console.warn(
        `WARNING: GSD command roster not found at ${gsdSrc}. ` +
        `Gemini /gsd- → /gsd: conversion will be a no-op. ` +
        `This usually means the package was installed without commands/gsd/.`
      );
    }
  }
  return _gsdCommandRoster;
}

// Test-only: reset the cached roster. Exported via GSD_TEST_MODE bundle below.
function _resetGsdCommandRoster() {
  _gsdCommandRoster = null;
  _gsdCommandRosterWarned = false;
}

function convertSlashCommandsToGeminiMentions(content) {
  const commands = getGsdCommandRoster();
  // Defense in depth: regex boundary AND roster lookup must both agree.
  //
  // - Lookbehind `(?<![A-Za-z0-9./])` rejects URLs (`example.com/gsd-…`),
  //   sub-paths (`bin/gsd-…`), and root-relative file paths preceded by a
  //   path char. Without it the roster alone is insufficient: a URL like
  //   `https://example.com/gsd-plan-phase` ends in a known command name and
  //   would convert incorrectly.
  // - `(?!\/)` rejects sub-path continuation (`/gsd-foo/bar`).
  // - `(?!\.[a-z])` rejects file extensions (`.cjs`, `.md`) but PERMITS
  //   sentence-ending punctuation like `/gsd-help.` because `.` at end of
  //   string or before whitespace is not followed by a lowercase letter.
  // - Roster lookup ensures only real commands convert — agent names like
  //   `gsd-planner` (no leading slash anyway) and unknown tokens pass through.
  //
  // GSD commands are always lowercase, so no case-insensitive flag.
  return content.replace(/(?<![A-Za-z0-9./])\/gsd-([a-z0-9-]+)(?!\/)(?!\.[a-z])/g, (match, commandName) => {
    return commands.has(commandName) ? `/gsd:${commandName}` : match;
  });
}

function convertClaudeToGeminiMarkdown(content, { isCommand = false, commandName = null } = {}) {
  // Apply Gemini-specific slash command namespacing
  let converted = convertSlashCommandsToGeminiMentions(content);
  // Gemini CLI does not expose Claude's AskUserQuestion tool. Convert body
  // references to runtime-neutral wording so converted agents do not instruct
  // Gemini to call a nonexistent tool (#3362).
  converted = converted.replace(/\b(?:AskUserQuestion|ask_user)\b/g, 'conversational prompting');
  // Strip HTML subscript tags — terminals can't render them. Done before
  // TOML conversion so the prompt body of a command file is also clean.
  converted = stripSubTags(converted);

  if (isCommand) {
    // Convert to Gemini TOML format (threads the command name so per-command
    // enrichment — e.g. the #778 live-state injection — can target a command).
    converted = convertClaudeToGeminiToml(converted, { commandName });
  }

  return converted;
}

function convertClaudeToGeminiAgent(content) {
  if (!content.startsWith('---')) return content;

  const endIndex = content.indexOf('---', 3);
  if (endIndex === -1) return content;

  const frontmatter = content.substring(3, endIndex).trim();
  const body = content.substring(endIndex + 3);

  const lines = frontmatter.split('\n');
  const newLines = [];
  let inAllowedTools = false;
  let inSkippedArrayField = false;
  const tools = [];

  for (const line of lines) {
    const trimmed = line.trim();

    if (inSkippedArrayField) {
      if (!trimmed || trimmed.startsWith('- ')) {
        continue;
      }
      inSkippedArrayField = false;
    }

    // Convert allowed-tools YAML array to tools list
    if (trimmed.startsWith('allowed-tools:')) {
      inAllowedTools = true;
      continue;
    }

    // Handle inline tools: field (comma-separated string)
    if (trimmed.startsWith('tools:')) {
      const toolsValue = trimmed.substring(6).trim();
      if (toolsValue) {
        const parsed = toolsValue.split(',').map(t => t.trim()).filter(t => t);
        for (const t of parsed) {
          const mapped = convertGeminiToolName(t);
          if (mapped) tools.push(mapped);
        }
      } else {
        // tools: with no value means YAML array follows
        inAllowedTools = true;
      }
      continue;
    }

    // Strip color field (not supported by Gemini CLI, causes validation error)
    if (trimmed.startsWith('color:')) continue;

    // Strip skills field (not supported by Gemini CLI, causes validation error)
    if (trimmed.startsWith('skills:')) {
      inSkippedArrayField = true;
      continue;
    }

    // Collect allowed-tools/tools array items
    if (inAllowedTools) {
      if (trimmed.startsWith('- ')) {
        const mapped = convertGeminiToolName(trimmed.substring(2).trim());
        if (mapped) tools.push(mapped);
        continue;
      } else if (trimmed && !trimmed.startsWith('-')) {
        inAllowedTools = false;
      }
    }

    if (!inAllowedTools) {
      newLines.push(line);
    }
  }

  // Add tools as YAML array (Gemini requires array format)
  if (tools.length > 0) {
    newLines.push('tools:');
    for (const tool of tools) {
      newLines.push(`  - ${tool}`);
    }
  }

  const newFrontmatter = newLines.join('\n').trim();

  // Escape ${VAR} patterns in agent body for Gemini CLI compatibility.
  // Gemini's templateString() treats all ${word} patterns as template variables
  // and throws "Template validation failed: Missing required input parameters"
  // when they can't be resolved. GSD agents use ${PHASE}, ${PLAN}, etc. as
  // shell variables in bash code blocks — convert to $VAR (no braces) which
  // is equivalent bash and invisible to Gemini's /\$\{(\w+)\}/g regex.
  const escapedBody = body.replace(/\$\{(\w+)\}/g, '$$$1');

  // Runtime-neutral agent name replacement (#766)
  const neutralBody = neutralizeAgentReferences(escapedBody, 'GEMINI.md');
  // Apply Gemini-specific transformations (slash commands + sub-tag stripping)
  const geminiBody = convertClaudeToGeminiMarkdown(neutralBody);
  return `---\n${newFrontmatter}\n---${geminiBody}`;
}

function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
  // Replace tool name references in content (applies to all files)
  let convertedContent = content;
  convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
  convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
  convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
  // Replace /gsd-command colon variant with /gsd-command for opencode (flat command structure)
  convertedContent = convertedContent.replace(/\/gsd:/g, '/gsd-');
  // Replace ~/.claude and $HOME/.claude with OpenCode's config location
  convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/opencode');
  convertedContent = convertedContent.replace(/\$HOME\/\.claude\b/g, '$HOME/.config/opencode');
  // Replace general-purpose subagent type with OpenCode's equivalent "general"
  convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
  // Runtime-neutral agent name replacement (#766)
  convertedContent = neutralizeAgentReferences(convertedContent, 'AGENTS.md');

  // Check if content has frontmatter
  if (!convertedContent.startsWith('---')) {
    return convertedContent;
  }

  // Find the end of frontmatter
  const endIndex = convertedContent.indexOf('---', 3);
  if (endIndex === -1) {
    return convertedContent;
  }

  const frontmatter = convertedContent.substring(3, endIndex).trim();
  const body = convertedContent.substring(endIndex + 3);

  // Parse frontmatter line by line (simple YAML parsing)
  const lines = frontmatter.split('\n');
  const newLines = [];
  let inAllowedTools = false;
  let inSkippedArray = false;
  const allowedTools = [];

  for (const line of lines) {
    const trimmed = line.trim();

    // For agents: skip commented-out lines (e.g. hooks blocks)
    if (isAgent && trimmed.startsWith('#')) {
      continue;
    }

    // Detect start of allowed-tools array
    if (trimmed.startsWith('allowed-tools:')) {
      inAllowedTools = true;
      continue;
    }

    // Detect inline tools: field (comma-separated string)
    if (trimmed.startsWith('tools:')) {
      if (isAgent) {
        // Agents: strip tools entirely (not supported in OpenCode agent frontmatter)
        inSkippedArray = true;
        continue;
      }
      const toolsValue = trimmed.substring(6).trim();
      if (toolsValue) {
        // Parse comma-separated tools
        const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
        allowedTools.push(...tools);
      }
      continue;
    }

    // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:, disallowedTools:
    if (isAgent && /^(skills|color|memory|maxTurns|permissionMode|disallowedTools):/.test(trimmed)) {
      inSkippedArray = true;
      continue;
    }

    // Skip continuation lines of a stripped array/object field
    if (inSkippedArray) {
      if (trimmed.startsWith('- ') || trimmed.startsWith('#') || /^\s/.test(line)) {
        continue;
      }
      inSkippedArray = false;
    }

    // For commands: remove name: field (opencode uses filename for command name)
    // For agents: keep name: (required by OpenCode agents)
    if (!isAgent && trimmed.startsWith('name:')) {
      continue;
    }

    // Strip model: field — OpenCode doesn't support Claude Code model aliases
    // like 'haiku', 'sonnet', 'opus', or 'inherit'. Omitting lets OpenCode use
    // its configured default model. See #1156.
    if (trimmed.startsWith('model:')) {
      continue;
    }

    // Convert color names to hex for opencode (commands only; agents strip color above)
    if (trimmed.startsWith('color:')) {
      const colorValue = trimmed.substring(6).trim().toLowerCase();
      const hexColor = colorNameToHex[colorValue];
      if (hexColor) {
        newLines.push(`color: "${hexColor}"`);
      } else if (colorValue.startsWith('#')) {
        // Validate hex color format (#RGB or #RRGGBB)
        if (/^#[0-9a-f]{3}$|^#[0-9a-f]{6}$/i.test(colorValue)) {
          // Already hex and valid, keep as is
          newLines.push(line);
        }
        // Skip invalid hex colors
      }
      // Skip unknown color names
      continue;
    }

    // Collect allowed-tools items
    if (inAllowedTools) {
      if (trimmed.startsWith('- ')) {
        allowedTools.push(trimmed.substring(2).trim());
        continue;
      } else if (trimmed && !trimmed.startsWith('-')) {
        // End of array, new field started
        inAllowedTools = false;
      }
    }

    // Keep other fields
    if (!inAllowedTools) {
      newLines.push(line);
    }
  }

  // For agents: add required OpenCode agent fields
  // Note: Do NOT add 'model: inherit' — OpenCode does not recognize the 'inherit'
  // keyword and throws ProviderModelNotFoundError. Omitting model: lets OpenCode
  // use its default model for subagents. See #1156.
  if (isAgent) {
    newLines.push('mode: subagent');
    // Embed model override from ~/.gsd/defaults.json so model_overrides is
    // respected on OpenCode (which uses static agent frontmatter, not inline
    // Task() model parameters). See #2256.
    if (modelOverride) {
      newLines.push(`model: ${modelOverride}`);
    }
  }

  // For commands: add tools object if we had allowed-tools or tools
  if (!isAgent && allowedTools.length > 0) {
    newLines.push('tools:');
    for (const tool of allowedTools) {
      newLines.push(`  ${convertToolName(tool)}: true`);
    }
  }

  // Rebuild frontmatter (body already has tool names converted)
  const newFrontmatter = newLines.join('\n').trim();
  return `---\n${newFrontmatter}\n---${body}`;
}

// Kilo CLI — same conversion logic as OpenCode, different config paths.
function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
  // Replace tool name references in content (applies to all files)
  let convertedContent = content;
  convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
  convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
  convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
  // Replace /gsd-command colon variant with /gsd-command for Kilo (flat command structure)
  convertedContent = convertedContent.replace(/\/gsd:/g, '/gsd-');
  // Replace ~/.claude and $HOME/.claude with Kilo's config location
  convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/kilo');
  convertedContent = convertedContent.replace(/\$HOME\/\.claude\b/g, '$HOME/.config/kilo');
  convertedContent = convertedContent.replace(/\.\/\.claude\//g, './.kilo/');
  // Normalize both Claude skill directory variants to Kilo's canonical skills dir.
  convertedContent = replaceRelativePathReference(convertedContent, '.claude/skills/', '.kilo/skills/');
  convertedContent = replaceRelativePathReference(convertedContent, '.agents/skills/', '.kilo/skills/');
  convertedContent = replaceRelativePathReference(convertedContent, '.claude/agents/', '.kilo/agents/');
  // Replace general-purpose subagent type with Kilo's equivalent "general"
  convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
  // Runtime-neutral agent name replacement (#766)
  convertedContent = neutralizeAgentReferences(convertedContent, 'AGENTS.md');

  // Check if content has frontmatter
  if (!convertedContent.startsWith('---')) {
    return convertedContent;
  }

  // Find the end of frontmatter
  const endIndex = convertedContent.indexOf('---', 3);
  if (endIndex === -1) {
    return convertedContent;
  }

  const frontmatter = convertedContent.substring(3, endIndex).trim();
  const body = convertedContent.substring(endIndex + 3);

  // Parse frontmatter line by line (simple YAML parsing)
  const lines = frontmatter.split('\n');
  const newLines = [];
  let inAllowedTools = false;
  let inAgentTools = false;
  let inSkippedArray = false;
  const allowedTools = [];
  const agentTools = [];

  for (const line of lines) {
    const trimmed = line.trim();

    // For agents: skip commented-out lines (e.g. hooks blocks)
    if (isAgent && trimmed.startsWith('#')) {
      continue;
    }

    // Detect start of allowed-tools array
    if (trimmed.startsWith('allowed-tools:')) {
      inAllowedTools = true;
      continue;
    }

    if (isAgent && inAgentTools) {
      if (trimmed.startsWith('- ')) {
        agentTools.push(trimmed.substring(2).trim());
        continue;
      }
      if (trimmed && !trimmed.startsWith('-')) {
        inAgentTools = false;
      }
    }

    // Detect inline tools: field (comma-separated string)
    if (trimmed.startsWith('tools:')) {
      if (isAgent) {
        const toolsValue = trimmed.substring(6).trim();
        if (toolsValue) {
          const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
          agentTools.push(...tools);
        } else {
          inAgentTools = true;
        }
        continue;
      }
      const toolsValue = trimmed.substring(6).trim();
      if (toolsValue) {
        // Parse comma-separated tools
        const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
        allowedTools.push(...tools);
      }
      continue;
    }

    // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:, disallowedTools:
    if (isAgent && /^(skills|color|memory|maxTurns|permissionMode|disallowedTools):/.test(trimmed)) {
      inSkippedArray = true;
      continue;
    }

    // Skip continuation lines of a stripped array/object field
    if (inSkippedArray) {
      if (trimmed.startsWith('- ') || trimmed.startsWith('#') || /^\s/.test(line)) {
        continue;
      }
      inSkippedArray = false;
    }

    // For commands: remove name: field (Kilo uses filename for command name)
    // For agents: keep name: (required by Kilo agents)
    if (!isAgent && trimmed.startsWith('name:')) {
      continue;
    }

    // Strip model: field — Kilo doesn't support Claude Code model aliases
    // like 'haiku', 'sonnet', 'opus', or 'inherit'. Omitting lets Kilo use
    // its configured default model.
    if (trimmed.startsWith('model:')) {
      continue;
    }

    // Convert color names to hex for Kilo (commands only; agents strip color above)
    if (trimmed.startsWith('color:')) {
      const colorValue = trimmed.substring(6).trim().toLowerCase();
      const hexColor = colorNameToHex[colorValue];
      if (hexColor) {
        newLines.push(`color: "${hexColor}"`);
      } else if (colorValue.startsWith('#')) {
        // Validate hex color format (#RGB or #RRGGBB)
        if (/^#[0-9a-f]{3}$|^#[0-9a-f]{6}$/i.test(colorValue)) {
          // Already hex and valid, keep as is
          newLines.push(line);
        }
        // Skip invalid hex colors
      }
      // Skip unknown color names
      continue;
    }

    // Collect allowed-tools items
    if (inAllowedTools) {
      if (trimmed.startsWith('- ')) {
        const tool = trimmed.substring(2).trim();
        if (isAgent) {
          agentTools.push(tool);
        } else {
          allowedTools.push(tool);
        }
        continue;
      } else if (trimmed && !trimmed.startsWith('-')) {
        // End of array, new field started
        inAllowedTools = false;
      }
    }

    // Keep other fields
    if (!inAllowedTools) {
      newLines.push(line);
    }
  }

  // For agents: add required Kilo agent fields
  if (isAgent) {
    newLines.push('mode: subagent');
    newLines.push(...buildKiloAgentPermissionBlock(agentTools));
  }

  // For commands: add tools object if we had allowed-tools or tools
  if (!isAgent && allowedTools.length > 0) {
    newLines.push('tools:');
    for (const tool of allowedTools) {
      newLines.push(`  ${convertToolName(tool)}: true`);
    }
  }

  // Rebuild frontmatter (body already has tool names converted)
  const newFrontmatter = newLines.join('\n').trim();
  return `---\n${newFrontmatter}\n---${body}`;
}

/**
 * Shared SKILL.md writer for the OpenCode-family runtimes (OpenCode + Kilo),
 * which share a config schema (Kilo derives from OpenCode). OpenCode discovers
 * skills as `skills/<name>/SKILL.md` and Kilo follows the same layout
 * (https://opencode.ai/docs/skills, https://kilo.ai/docs/customize/skills).
 *
 * The skill body reuses the runtime's command-frontmatter converter for tool,
 * path, and `/gsd:`→`/gsd-` body rewrites, then rebuilds a minimal skill
 * frontmatter: only `name` (lowercase-hyphen, must match the containing
 * directory) and `description` (1–1024 chars) are emitted, per the OpenCode
 * skill spec. The command's `tools:`/`permission:` block is intentionally
 * dropped — OpenCode skills are loaded on-demand via the native skill tool and
 * inherit the calling agent's permissions.
 *
 * @param {string} content - Claude command markdown (with YAML frontmatter)
 * @param {string} skillName - Skill directory name (e.g. gsd-help)
 * @param {(content: string) => string} frontmatterConverter - runtime command converter
 * @returns {string} SKILL.md content
 */
function convertClaudeCommandToOpencodeFamilySkill(content, skillName, frontmatterConverter) {
  const converted = frontmatterConverter(content);
  const { frontmatter, body } = extractFrontmatterAndBody(converted);
  let description = `Run GSD workflow ${skillName}.`;
  if (frontmatter) {
    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
    if (maybeDescription) {
      description = maybeDescription;
    }
  }
  description = toSingleLine(description);
  // OpenCode skill descriptions must be 1–1024 characters.
  if (description.length > 1024) {
    description = `${description.slice(0, 1021)}...`;
  }
  // `name` must be lowercase alphanumeric with single-hyphen separators and
  // match the containing directory name (the staged dir is `${skillName}/`).
  const name = yamlIdentifier(skillName);
  return `---\nname: ${name}\ndescription: ${yamlQuote(description)}\n---\n\n${body.trimStart()}`;
}

/**
 * Convert a Claude command (.md) to an OpenCode skill (SKILL.md).
 * Thin wrapper over the shared OpenCode-family writer.
 */
function convertClaudeCommandToOpencodeSkill(content, skillName) {
  return convertClaudeCommandToOpencodeFamilySkill(
    content,
    skillName,
    (c) => convertClaudeToOpencodeFrontmatter(c),
  );
}

/**
 * Convert a Claude command (.md) to a Kilo skill (SKILL.md).
 * Thin wrapper over the shared OpenCode-family writer (Kilo shares the schema).
 */
function convertClaudeCommandToKiloSkill(content, skillName) {
  return convertClaudeCommandToOpencodeFamilySkill(
    content,
    skillName,
    (c) => convertClaudeToKiloFrontmatter(c),
  );
}

/**
 * Convert Claude Code markdown command to Gemini TOML format
 * @param {string} content - Markdown file content with YAML frontmatter
 * @returns {string} - TOML content
 */
function convertClaudeToGeminiToml(content, { commandName = null } = {}) {
  // #778 (c) — Gemini {{args}} interpolation. Claude's $ARGUMENTS placeholder
  // maps to Gemini's {{args}} so inline argument references interpolate into the
  // command body instead of being emitted as a dead literal. Applied before
  // frontmatter parsing so every return path benefits (a command's frontmatter
  // never contains $ARGUMENTS, so this is body-only in practice). Gemini injects
  // {{args}} as typed outside shell blocks; we never place it inside a !{...}
  // block, so there is no shell-escaping/injection interaction.
  content = content.replace(/\$ARGUMENTS\b/g, '{{args}}');

  // Check if content has frontmatter
  if (!content.startsWith('---')) {
    return `prompt = ${JSON.stringify(content)}\n`;
  }

  const endIndex = content.indexOf('---', 3);
  if (endIndex === -1) {
    return `prompt = ${JSON.stringify(content)}\n`;
  }

  const frontmatter = content.substring(3, endIndex).trim();
  let body = content.substring(endIndex + 3).trim();

  // #778 (c) — Gemini !{...} dynamic-output injection for the situational
  // `progress` command (GSD's status/dashboard surface). Inject the live
  // .planning/STATE.md so the model sees current project state without relying
  // on session memory.
  //
  // SECURITY: the shell command is a FIXED `cat` with NO interpolated user
  // input — no {{args}} appears inside the block — so there is no
  // shell-injection vector. Gemini still shows its standard per-invocation
  // confirmation dialog (verified behavior). `2>/dev/null` keeps an
  // uninitialized project (missing STATE.md) from injecting stderr noise.
  // Braces inside the block are balanced (none present), per Gemini's parser
  // requirement. The append happens AFTER the {{args}} mapping above so the
  // injected block can never accidentally carry interpolated arguments.
  if (commandName === 'progress') {
    body += '\n\n## Live project state\n'
      + 'Current contents of `.planning/STATE.md` '
      + '(empty if the project is not yet initialized):\n\n'
      + '!{cat .planning/STATE.md 2>/dev/null}\n';
  }

  // Extract description from frontmatter
  let description = '';
  const lines = frontmatter.split('\n');
  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed.startsWith('description:')) {
      description = trimmed.substring(12).trim();
      break;
    }
  }

  // Construct TOML
  let toml = '';
  if (description) {
    toml += `description = ${JSON.stringify(description)}\n`;
  }

  toml += `prompt = ${JSON.stringify(body)}\n`;

  return toml;
}

/**
 * Copy commands to a flat structure for OpenCode
 * OpenCode expects: command/gsd-help.md (invoked as /gsd-help)
 * Source structure: commands/gsd/help.md
 * 
 * @param {string} srcDir - Source directory (e.g., commands/gsd/)
 * @param {string} destDir - Destination directory (e.g., command/)
 * @param {string} prefix - Prefix for filenames (e.g., 'gsd')
 * @param {string} pathPrefix - Path prefix for file references
 * @param {string} runtime - Target runtime ('claude', 'opencode', or 'kilo')
 */
/**
 * Apply OpenCode-family (`opencode`/`kilo`) `@file` path-prefix rewrites to a
 * RAW Claude command/skill body, BEFORE the frontmatter converter runs.
 *
 * This is the single source of truth shared by copyFlattenedCommands (commands)
 * and installOpencodeFamilySkills (skills) so the two surfaces produce identical
 * path references. Applying pathPrefix pre-conversion (rather than rewriting an
 * already-converted body) is what avoids the converter's hardcoded default
 * config dir leaking into --local / --config-dir installs, and the
 * prefix-overlap double-rewrite hazard for custom dirs like `kilo-alt`. (#784)
 *
 * @param {string} content - raw Claude command markdown
 * @param {string} runtime - 'opencode' or 'kilo'
 * @param {string} pathPrefix - trailing-slash install-target prefix
 * @returns {string}
 */
function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
  content = content.replace(/~\/\.claude\//g, pathPrefix);
  content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
  content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
  content = content.replace(/~\/\.opencode\//g, pathPrefix);
  content = content.replace(/~\/\.kilo\//g, pathPrefix);
  return content;
}

function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
  if (!fs.existsSync(srcDir)) {
    return;
  }

  // Remove old gsd-*.md files before copying new ones
  if (fs.existsSync(destDir)) {
    for (const file of fs.readdirSync(destDir)) {
      if (file.startsWith(`${prefix}-`) && file.endsWith('.md')) {
        fs.unlinkSync(path.join(destDir, file));
      }
    }
  } else {
    fs.mkdirSync(destDir, { recursive: true });
  }

  const entries = fs.readdirSync(srcDir, { withFileTypes: true });

  for (const entry of entries) {
    const srcPath = path.join(srcDir, entry.name);

    if (entry.isDirectory()) {
      // Recurse into subdirectories, adding to prefix
      // e.g., commands/gsd/debug/start.md -> command/gsd-debug-start.md
      copyFlattenedCommands(srcPath, destDir, `${prefix}-${entry.name}`, pathPrefix, runtime);
    } else if (entry.name.endsWith('.md')) {
      // Flatten: help.md -> gsd-help.md
      const baseName = entry.name.replace('.md', '');
      const destName = `${prefix}-${baseName}.md`;
      const destPath = path.join(destDir, destName);

      let content = fs.readFileSync(srcPath, 'utf8');
      content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      content = runtime === 'kilo'
        ? convertClaudeToKiloFrontmatter(content)
        : convertClaudeToOpencodeFrontmatter(content);

      fs.writeFileSync(destPath, content);
    }
  }
}

function listCodexSkillNames(skillsDir, prefix = 'gsd-') {
  if (!fs.existsSync(skillsDir)) return [];
  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
  return entries
    .filter(entry => entry.isDirectory() && entry.name.startsWith(prefix))
    .filter(entry => fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')))
    .map(entry => entry.name)
    .sort();
}

/**
 * Generic skills install helper used by all copyCommandsAs*Skills shims.
 *
 * Recursively walks srcDir, applies converter to each .md file (mirroring the
 * old per-function recurse() bodies), applies runtime content rewrites
 * (path + branding), and writes each skill as <prefix>-<stem>/SKILL.md under
 * skillsDir. Replaces the ~50-line recursion bodies in the 9 old functions.
 *
 * @param {string} srcDir          source commands directory
 * @param {string} skillsDir       destination skills directory
 * @param {string} prefix          skill name prefix without trailing dash (e.g. 'gsd')
 * @param {string} pathPrefix      trailing-slash path prefix for content rewrites
 * @param {string} runtime         canonical runtime ID for rewrite table
 * @param {Function} converter     wrapped converter (content, skillName) → string
 */



/**
 * Copy Claude commands as Windsurf skills — one folder per skill with SKILL.md.
 * Mirrors copyCommandsAsCursorSkills but uses Windsurf converters.
 */


/**
 * Copy Claude commands as CodeBuddy skills — one folder per skill with SKILL.md.
 * CodeBuddy uses the same tool names as Claude Code, but has its own config directory structure.
 */

/**
 * Copy Claude commands as Copilot skills — one folder per skill with SKILL.md.
 * Applies CONV-01 (structure), CONV-02 (allowed-tools), CONV-06 (paths), CONV-07 (command names).
 */

/**
 * Copy Claude commands as Claude skills — one folder per skill with SKILL.md.
 * Claude Code 2.1.88+ uses skills/xxx/SKILL.md instead of commands/gsd/xxx.md.
 * Supports runtime='claude'|'qwen'|'hermes'; branding rewrites are applied via
 * applyRuntimeContentRewritesInPlace inside _copyCommandsAsSkillsViaConverter.
 * @param {string} srcDir - Source commands directory
 * @param {string} skillsDir - Target skills directory
 * @param {string} prefix - Skill name prefix (e.g. 'gsd')
 * @param {string} pathPrefix - Path prefix for file references
 * @param {string} runtime - Target runtime
 * @param {boolean} isGlobal - Whether this is a global install (unused; kept for compat)
 */

/**
 * Write the Hermes "gsd" category DESCRIPTION.md.
 * Hermes' skill loader reads DESCRIPTION.md at the top of each skill category
 * directory and surfaces it in the system prompt so the model knows when to
 * reach for that category. Per spec in #2841 we collapse all 86 GSD commands
 * under a single "gsd" category to keep system-prompt overhead bounded.
 */
function writeHermesCategoryDescription(categoryDir) {
  fs.mkdirSync(categoryDir, { recursive: true });
  const body = [
    '---',
    'name: gsd',
    `version: ${pkg.version}`,
    'description: GSD Core — Git. Ship. Done. Disciplined planning, execution, and shipping workflows. Use any gsd-* skill in this category to drive a project through new-project → discuss-phase → plan-phase → execute-phase → ship.',
    '---',
    '',
    '# GSD Core',
    '',
    'GSD is a structured development workflow. Skills in this category cover',
    'project initialization, phase planning, execution, code review, and shipping.',
    '',
    'Invoke any `gsd-*` skill in this category to drive the corresponding step.',
    '',
  ].join('\n');
  fs.writeFileSync(path.join(categoryDir, 'DESCRIPTION.md'), body);
}

/**
 * Recursively install GSD commands as Antigravity skills.
 * Each command becomes a skill-name/ folder containing SKILL.md.
 * Mirrors copyCommandsAsCopilotSkills but uses Antigravity converters.
 * @param {string} srcDir - Source commands directory
 * @param {string} skillsDir - Target skills directory
 * @param {string} prefix - Skill name prefix (e.g. 'gsd')
 * @param {boolean} isGlobal - Whether this is a global install
 */

/**
 * Single source of truth for user-owned artifacts inside gsd-core/.
 *
 * These files are created/refreshed by user-facing workflows (e.g.
 * /gsd-profile-user) and must be preserved across reinstalls. Critically, they
 * MUST be excluded from gsd-file-manifest.json — otherwise saveLocalPatches()
 * will compare a refreshed file against a stale manifest hash and emit a
 * spurious "locally modified GSD file" warning (bug #2771).
 *
 * Invariant: a file is either distribution (manifest-tracked, diff'd against
 * manifest) or user artifact (preserved across installs, never diff'd). Never
 * both. Both preserveUserArtifacts call sites and writeManifest must agree on
 * this list, which is why it lives here as a single constant.
 *
 * Paths are relative to the gsd-core/ directory.
 */
const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];

/**
 * Save user-generated files from destDir to an in-memory map before a wipe.
 *
 * @param {string} destDir - Directory that is about to be wiped
 * @param {string[]} fileNames - Relative file names (e.g. ['USER-PROFILE.md']) to preserve
 * @returns {Map<string, string>} Map of fileName → file content (only entries that existed)
 */
function preserveUserArtifacts(destDir, fileNames) {
  const saved = new Map();
  for (const name of fileNames) {
    const fullPath = path.join(destDir, name);
    if (fs.existsSync(fullPath)) {
      try {
        saved.set(name, fs.readFileSync(fullPath, 'utf8'));
      } catch { /* skip unreadable files */ }
    }
  }
  return saved;
}

/**
 * Restore user-generated files saved by preserveUserArtifacts after a wipe.
 *
 * @param {string} destDir - Directory that was wiped and recreated
 * @param {Map<string, string>} saved - Map returned by preserveUserArtifacts
 */
function restoreUserArtifacts(destDir, saved) {
  for (const [name, content] of saved) {
    const fullPath = path.join(destDir, name);
    try {
      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
      fs.writeFileSync(fullPath, content, 'utf8');
    } catch { /* skip unwritable paths */ }
  }
}

/**
 * Migrate a legacy dev-preferences.md (saved from commands/gsd/) into the
 * runtime-aware SKILL.md location used by the writer after #2973.
 *
 * For runtimes with a nested skills layout (e.g. Hermes: skills/gsd/<stem>/),
 * the target is <configDir>/skills/gsd/dev-preferences/SKILL.md.
 * For runtimes with a flat skills layout (prefix='gsd-'), the target is
 * <configDir>/skills/gsd-dev-preferences/SKILL.md.
 *
 * Skips silently if no legacy file was preserved, or if a SKILL.md already
 * exists at the new location (don't clobber user-customized skill content
 * — they may have edited the new file directly). Returns true on actual
 * migration so callers can log a one-line confirmation.
 *
 * @param {string} targetDir - Resolved runtime config directory (e.g. ~/.claude)
 * @param {Map<string, string>} saved - Map returned by preserveUserArtifacts
 * @param {string} [runtime] - canonical runtime ID (e.g. 'hermes', 'qwen', 'claude')
 * @param {'global'|'local'} [scope] - install scope
 * @returns {boolean} - true if a file was migrated, false otherwise
 */
function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = 'global') {
  if (!saved || !saved.has('dev-preferences.md')) return false;
  let skillDir;
  if (runtime) {
    const layout = resolveRuntimeArtifactLayout(runtime, targetDir, scope);
    const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
    if (!skillsKindEntry) return false; // runtime has no skills layout at this scope (e.g. cline local)
    const stemName = skillsKindEntry.prefix === '' ? 'dev-preferences' : 'gsd-dev-preferences';
    skillDir = path.join(targetDir, skillsKindEntry.destSubpath, stemName);
  } else {
    // Legacy fallback for callers that have not yet been updated to pass runtime
    skillDir = path.join(targetDir, 'skills', 'gsd-dev-preferences');
  }
  const skillFile = path.join(skillDir, 'SKILL.md');
  if (fs.existsSync(skillFile)) return false;
  try {
    fs.mkdirSync(skillDir, { recursive: true });
    fs.writeFileSync(skillFile, saved.get('dev-preferences.md'), 'utf8');
    return true;
  } catch {
    return false;
  }
}

// ---------------------------------------------------------------------------
// Phase 2 — Layout-driven install/uninstall orchestrators
// ---------------------------------------------------------------------------

/**
 * Apply per-runtime content rewrites in place across every SKILL.md inside a
 * staged directory. Reproduces the rewrite scaffolding that the old
 * copyCommandsAs<Runtime>Skills functions applied between read-content and
 * converter-call. Applied AFTER stage (which already called the converter);
 * rewrites target stable path patterns the converter doesn't touch.
 *
 * For Qwen/Hermes, branding rewrites (.claude/ → .qwen/ / .hermes/) run
 * AFTER the slash-form path replacements but they only catch bare `.claude/`
 * patterns (skill-body relative refs) that the slash forms didn't consume.
 * This mirrors the exact ordering in the legacy copyCommandsAsClaudeSkills body.
 *
 * @param {string} stagedDir
 * @param {string} runtime
 * @param {string} pathPrefix  e.g. "~/.codex/" — trailing-slash string
 */
function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix) {
  if (!fs.existsSync(stagedDir)) return;

  // Walk all SKILL.md files under stagedDir
  const walkAndRewrite = (dir) => {
    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
      const fullPath = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        walkAndRewrite(fullPath);
      } else if (entry.name.endsWith('.md')) {
        let content = fs.readFileSync(fullPath, 'utf8');
        content = _applyRuntimeRewrites(content, runtime, pathPrefix);
        fs.writeFileSync(fullPath, content);
      }
    }
  };
  walkAndRewrite(stagedDir);
}

/**
 * Apply per-runtime content rewrites to flat .md files in a staged commands dir.
 * Used for runtimes that have a commandsKind in their layout and need content rewrites
 * (e.g. augment — replaces ~/.claude/ paths and applies branding conversions).
 *
 * IMPORTANT: `stageSkillsForProfile()` returns the original source directory unchanged
 * on a full/default profile (skills === '*'). This function MUST NOT mutate that source
 * directory. It always copies to a temp dir first, rewrites there, and returns the new
 * path so the caller installs from the temp copy, not the source.
 *
 * @param {string} stagedDir  directory of staged flat .md command files (may be source dir)
 * @param {string} runtime
 * @param {string} pathPrefix
 * @returns {string}  path to a temp dir with rewritten files (caller is responsible for cleanup)
 */
function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix) {
  if (!fs.existsSync(stagedDir)) return stagedDir;
  // Always copy to a temp dir — stageSkillsForProfile() returns the original source
  // dir on full/default profile (skills === '*'), so writing in-place would corrupt the
  // package source. A temp copy is unconditional to keep the code simple and safe.
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-cmd-rewrites-'));
  try {
    for (const entry of fs.readdirSync(stagedDir, { withFileTypes: true })) {
      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
      let content = fs.readFileSync(path.join(stagedDir, entry.name), 'utf8');
      content = _applyRuntimeRewrites(content, runtime, pathPrefix);
      // For augment commands, apply the markdown conversion so tool references
      // and skill paths use Augment equivalents.
      if (runtime === 'augment') {
        content = convertClaudeToAugmentMarkdown(content);
      }
      fs.writeFileSync(path.join(tempDir, entry.name), content);
    }
  } catch (err) {
    try { fs.rmSync(tempDir, { recursive: true, force: true }); } catch { /* best-effort */ }
    throw err;
  }
  return tempDir;
}

/**
 * Apply the per-runtime rewrite table to a single content string.
 * Extracted so it can be unit-tested independently of the filesystem walk.
 *
 * @param {string} content
 * @param {string} runtime
 * @param {string} pathPrefix  trailing-slash string
 * @returns {string}
 */
function _applyRuntimeRewrites(content, runtime, pathPrefix) {
  const dirName = getDirName(runtime);
  const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');

  switch (runtime) {
    case 'codex':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.codex\//g, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'cline':
      // Slash forms: both the original ~/.claude/ (safety net) and the stage-time
      // converted ~/.cline/ (from convertClaudeToCliineMarkdown) → pathPrefix
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.cline\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.cline\//g, pathPrefix);
      // Bare forms (no trailing slash)
      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/~\/\.cline\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.cline\b/g, normalizedPathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'cursor':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.cursor\//g, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'windsurf':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.codeium\/windsurf\//g, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'augment':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.augment\//g, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'trae':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
      content = content.replace(/~\/\.trae\//g, pathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'codebuddy':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
      // The codebuddy converter rewrites `.claude/` → `.codebuddy/` at stage
      // time, so `$HOME/.claude/...` arrives here as `$HOME/.codebuddy/...`.
      // Normalize BOTH the `~/` and `$HOME/` forms (slash + bare) to the install
      // target so `--config-dir`/local installs don't leak the default home.
      content = content.replace(/~\/\.codebuddy\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.codebuddy\//g, pathPrefix);
      content = content.replace(/~\/\.codebuddy\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.codebuddy\b/g, normalizedPathPrefix);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'copilot':
      // Copilot converter handles path rewrites; only attribution here
      content = processAttribution(content, getCommitAttribution('copilot'));
      break;

    case 'antigravity':
      // Antigravity converter handles path rewrites; only attribution here
      content = processAttribution(content, getCommitAttribution('antigravity'));
      break;

    case 'claude':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'qwen':
      // Branding rewrites run before path rewrites to avoid consuming
      // patterns that the path step would also match.
      content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
      content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
      // Base path rewrites (use ~/ and $HOME/ slash forms first — most specific)
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/~\/\.qwen\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.qwen\//g, pathPrefix);
      // Bare relative .claude/ → .qwen/ (residual refs not matched above)
      content = content.replace(/\.claude\//g, '.qwen/');
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/\.\/\.qwen\//g, `./${dirName}/`);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'hermes':
      // Branding rewrites run before path rewrites (same rationale as qwen)
      content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
      content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
      // Base path rewrites
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/~\/\.hermes\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.hermes\//g, pathPrefix);
      // Bare relative .claude/ → .hermes/ (residual refs)
      content = content.replace(/\.claude\//g, '.hermes/');
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/\.\/\.hermes\//g, `./${dirName}/`);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    case 'kimi':
      content = content.replace(/~\/\.claude\//g, pathPrefix);
      content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
      content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
      content = processAttribution(content, getCommitAttribution(runtime));
      break;

    default:
      // Unknown runtime — no rewrites.
      // OpenCode/Kilo are intentionally absent: their skills are written by
      // installOpencodeFamilySkills, which applies pathPrefix BEFORE the
      // command→skill conversion (mirroring copyFlattenedCommands) rather than
      // rewriting already-converted SKILL.md bodies. See #784.
      break;
  }

  return content;
}

/**
 * Copy a staged directory's contents into destDir.
 * Additive — does not prune (surface.cjs handles pruning).
 *
 * For skills kind: each child of stagedDir is a `${prefix}${stem}/` dir; copy
 *   the whole dir into destDir.
 * For commands/agents kind: iterate .md files and write them into destDir.
 *   - commands: write as `${prefix}${stem}.md` unless destSubpath already
 *     encodes the GSD namespace as its last segment (e.g. `commands/gsd`), in
 *     which case write as `${stem}.md` (directory IS the namespace).
 *   - agents: write as-is (files already carry their own `gsd-` prefix).
 * For kimi-agents kind: recursively copy generated YAML/prompt files.
 */
function _copyStaged(stagedDir, destDir, kind) {
  if (!fs.existsSync(stagedDir)) return;
  fs.mkdirSync(destDir, { recursive: true });

  if (kind.kind === 'skills') {
    // Each child of stagedDir is a prefixed skill directory: gsd-help/, etc.
    for (const entry of fs.readdirSync(stagedDir, { withFileTypes: true })) {
      if (!entry.isDirectory()) continue;
      const src = path.join(stagedDir, entry.name);
      const dest = path.join(destDir, entry.name);
      fs.cpSync(src, dest, { recursive: true });
    }
    return;
  }

  if (kind.kind === 'kimi-agents') {
    fs.cpSync(stagedDir, destDir, { recursive: true });
    return;
  }

  // commands or agents
  const entries = fs.readdirSync(stagedDir, { withFileTypes: true });
  // For commands: apply prefix unless the destSubpath's last segment already
  // represents the GSD namespace (e.g. 'commands/gsd' → last segment 'gsd').
  const destLast = path.basename(kind.destSubpath);
  const prefixStem = kind.prefix ? kind.prefix.replace(/-$/, '') : '';
  const namespacedByDir = kind.kind === 'commands' && destLast === prefixStem;

  for (const entry of entries) {
    if (!entry.isFile()) continue;
    if (!entry.name.endsWith('.md')) continue;
    const stem = entry.name.slice(0, -3); // strip .md

    let destName;
    if (kind.kind === 'agents') {
      // Agent files already carry the gsd- prefix in the source dir
      destName = entry.name;
    } else if (namespacedByDir) {
      // Directory is the namespace; don't double-prefix the filename
      destName = entry.name;
    } else {
      // Flat commands directory (e.g. command/ for opencode/kilo)
      destName = `${kind.prefix}${stem}.md`;
    }

    fs.copyFileSync(path.join(stagedDir, entry.name), path.join(destDir, destName));
  }
}

/**
 * Remove GSD-prefixed entries from destDir matching kind.prefix.
 * For Hermes nested case (prefix === ''): the destSubpath IS the namespace
 * (skills/gsd) — remove the entire destDir.
 */
function _removeGsdEntries(destDir, kind) {
  if (!fs.existsSync(destDir)) return;
  if (kind.kind === 'kimi-agents') {
    for (const fileName of ['gsd.yaml', 'gsd.md']) {
      fs.rmSync(path.join(destDir, fileName), { force: true });
    }
    const subagentsDir = path.join(destDir, 'subagents');
    if (fs.existsSync(subagentsDir)) {
      for (const entry of fs.readdirSync(subagentsDir, { withFileTypes: true })) {
        if (!entry.isFile()) continue;
        if (!entry.name.startsWith('gsd-')) continue;
        if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.md')) continue;
        fs.rmSync(path.join(subagentsDir, entry.name), { force: true });
      }
    }
    return;
  }
  if (kind.prefix === '') {
    // Whole-namespace removal (Hermes nested case — destSubpath is skills/gsd)
    // The directory itself is the GSD namespace, so remove it entirely.
    fs.rmSync(destDir, { recursive: true, force: true });
    return;
  }
  for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
    if (!entry.name.startsWith(kind.prefix)) continue;
    fs.rmSync(path.join(destDir, entry.name), { recursive: true, force: true });
  }
}

/**
 * Run legacy install migrations that must execute BEFORE the layout-driven
 * copy so stale artifacts are cleaned up before new ones are written.
 *
 * - Claude/Qwen/Hermes: migrate legacy commands/gsd/dev-preferences.md →
 *   skills/gsd-dev-preferences/SKILL.md if the old file is present.
 *   Also removes the legacy commands/gsd/ directory.
 * - Hermes: remove flat skills/gsd-STAR directories (pre-2841 layout) before
 *   writing the new nested skills/gsd/ layout.
 *
 * @param {string} runtime
 * @param {string} configDir  resolved runtime config directory
 * @param {'global'|'local'} [scope]
 */
function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
  const legacyCommandsGsd = path.join(configDir, 'commands', 'gsd');

  // Claude / Qwen / Hermes: clean up legacy commands/gsd/ and preserve dev-preferences
  // for migration. The actual migration call is deferred to after all layout cleanup so
  // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
  // created skills/gsd-dev-preferences/ skill dir.
  let savedLegacyArtifacts = null;
  if (runtime === 'claude' || runtime === 'qwen' || runtime === 'hermes') {
    if (fs.existsSync(legacyCommandsGsd)) {
      savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
      fs.rmSync(legacyCommandsGsd, { recursive: true });
    }
  }

  // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
  // the new skills/gsd/ nested layout.
  if (runtime === 'hermes') {
    const flatSkillsDir = path.join(configDir, 'skills');
    if (fs.existsSync(flatSkillsDir)) {
      for (const entry of fs.readdirSync(flatSkillsDir, { withFileTypes: true })) {
        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
          fs.rmSync(path.join(flatSkillsDir, entry.name), { recursive: true });
        }
      }
    }

    // Hermes: remove intermediate-layout skills/gsd/gsd-*/ entries that existed
    // between #2841 and #3664. Phase 2 (#3664) uses prefix='' producing bare-stem
    // names (skills/gsd/<stem>/SKILL.md); the intermediate layout had the gsd-
    // prefix inside the nested dir (skills/gsd/gsd-<stem>/SKILL.md). Only
    // children whose name starts with gsd- are removed — the parent skills/gsd/
    // directory and any non-gsd- siblings (user content) are preserved.
    const nestedGsdDir = path.join(configDir, 'skills', 'gsd');
    if (fs.existsSync(nestedGsdDir)) {
      for (const entry of fs.readdirSync(nestedGsdDir, { withFileTypes: true })) {
        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
          fs.rmSync(path.join(nestedGsdDir, entry.name), { recursive: true });
        }
      }
    }
  }

  // Migrate dev-preferences.md content → runtime-aware SKILL.md location (#2973).
  // Done after all layout cleanup so Hermes flat-dir removal does not delete the
  // newly created skill dir. No-op if skill file already exists.
  if (savedLegacyArtifacts) {
    migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
  }
}

/**
 * Run legacy uninstall cleanup that must execute BEFORE the layout-driven
 * removal so old-format entries are also cleaned up.
 *
 * - Claude global/Qwen: remove legacy commands/gsd/ directory if present.
 *   For Claude LOCAL, commands/gsd/ is the current primary location (not
 *   legacy), so we skip removal here and let _removeGsdEntries handle it
 *   with gsd- prefix filtering (preserving user files like dev-preferences.md).
 * - Hermes: remove pre-2841 flat skills/gsd-STAR entries.
 *
 * @param {string} runtime
 * @param {string} configDir  resolved runtime config directory
 * @param {'global'|'local'} [scope]
 */
function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  // Claude global / Qwen: commands/gsd/ is a legacy location (global Claude
  // uses skills/ now; Qwen always uses skills/). Remove whole directory.
  // Claude local: commands/gsd/ is the primary current location — skip here,
  // let layout's _removeGsdEntries handle gsd-prefixed file removal.
  // #2973 / Codex review (bd1f06c9): preserve user-owned dev-preferences.md
  // before destructive wipe. Migration to skills/gsd-dev-preferences/SKILL.md
  // is deferred and returned so the caller can apply it AFTER layout-driven
  // removal — this prevents the layout's gsd-* prefix removal from wiping the
  // freshly created skill dir (same pattern as _runLegacyInstallMigrations).
  let savedLegacyArtifacts = null;
  // commands/gsd/ is a legacy location for Qwen, Hermes, and Claude-global.
  // Claude-local commands/gsd/ is the primary current location — skip here.
  const isLegacyCommandsGsd = runtime === 'qwen' || runtime === 'hermes' || (runtime === 'claude' && scope === 'global');
  if (isLegacyCommandsGsd) {
    const legacyCommandsGsd = path.join(configDir, 'commands', 'gsd');
    if (fs.existsSync(legacyCommandsGsd)) {
      savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
      fs.rmSync(legacyCommandsGsd, { recursive: true });
    }
  }

  // Hermes: pre-#2841 flat skills/gsd-*/ entries
  if (runtime === 'hermes') {
    const flatSkillsDir = path.join(configDir, 'skills');
    if (fs.existsSync(flatSkillsDir)) {
      for (const entry of fs.readdirSync(flatSkillsDir, { withFileTypes: true })) {
        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
          fs.rmSync(path.join(flatSkillsDir, entry.name), { recursive: true });
        }
      }
    }
  }

  // Return saved artifacts so the caller can migrate after layout-driven removal.
  return savedLegacyArtifacts;
}

/**
 * Layout-driven install orchestrator.
 * Runs legacy migrations first, then uses resolveRuntimeArtifactLayout to
 * determine what artifact kinds to write and where.
 *
 * @param {string} runtime             canonical runtime ID
 * @param {string} configDir           resolved runtime config directory
 * @param {'global'|'local'} scope
 * @param {Object} resolvedProfile     from resolveProfile() / resolveEffectiveProfile()
 */
/**
 * Deep-snapshot a directory tree into a Map<relPath, Buffer>.
 * Returns an empty Map if the directory doesn't exist.
 * @param {string} dir
 * @returns {Map<string, Buffer>}
 */
function _snapshotDir(dir) {
  const files = new Map();
  if (!fs.existsSync(dir)) return files;
  const walk = (relPath, absPath) => {
    for (const e of fs.readdirSync(absPath, { withFileTypes: true })) {
      const childRel = relPath ? path.join(relPath, e.name) : e.name;
      const childAbs = path.join(absPath, e.name);
      if (e.isDirectory()) walk(childRel, childAbs);
      else if (e.isFile()) files.set(childRel, fs.readFileSync(childAbs));
    }
  };
  walk('', dir);
  return files;
}

/**
 * Restore a directory tree from a Map<relPath, Buffer> produced by _snapshotDir.
 * @param {string} dir
 * @param {Map<string, Buffer>} snapshot
 */
function _restoreDir(dir, snapshot) {
  for (const [relPath, buf] of snapshot) {
    const absPath = path.join(dir, relPath);
    fs.mkdirSync(path.dirname(absPath), { recursive: true });
    fs.writeFileSync(absPath, buf);
  }
}

function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile) {
  // Legacy cleanup before layout-driven writes
  _runLegacyInstallMigrations(runtime, configDir, scope);

  const layout = resolveRuntimeArtifactLayout(runtime, configDir, scope);

  // Compute pathPrefix once for the rewrite step (same derivation as the
  // top-level install() function).
  const _resolvedTarget = path.resolve(configDir).replace(/\\/g, '/');
  const _homeDir = os.homedir().replace(/\\/g, '/');
  const pathPrefix = computePathPrefix({
    isGlobal: scope === 'global',
    isOpencode: runtime === 'opencode',
    isWindowsHost: process.platform === 'win32',
    resolvedTarget: _resolvedTarget,
    homeDir: _homeDir,
  });

  for (const kind of layout.kinds) {
    const staged = kind.stage(resolvedProfile);
    // stagedForCopy: the directory to copy from (may differ from staged if rewrites
    // produce a temp copy — see applyRuntimeContentRewritesForCommandsInPlace).
    let stagedForCopy = staged;
    if (kind.kind === 'skills' || kind.kind === 'kimi-agents') {
      applyRuntimeContentRewritesInPlace(staged, runtime, pathPrefix);
    } else if (kind.kind === 'commands') {
      // Returns a temp dir with rewritten content so source files are never mutated.
      stagedForCopy = applyRuntimeContentRewritesForCommandsInPlace(staged, runtime, pathPrefix);
    }
    // applyRuntimeContentRewritesForCommandsInPlace() returns a fresh mkdtemp dir under
    // os.tmpdir() (gsd-cmd-rewrites-*); remove it once copied so it does not accumulate (#856).
    const tempToClean = stagedForCopy !== staged ? stagedForCopy : null;
    try {
      const dest = path.join(layout.configDir, kind.destSubpath);
      fs.mkdirSync(dest, { recursive: true });
      if (kind.kind === 'skills' && fs.existsSync(dest)) {
        // Pre-prune: snapshot user-owned content before _removeGsdEntries wipes it,
        // then restore after. This preserves user dirs across a wipe-and-replace
        // install (#2973 / #3664).
        //
        // For prefix='' (Hermes): _removeGsdEntries wipes the entire dest dir (skills/gsd/).
        // Preserve every subdir that is NOT in the staged set — those are user-added dirs
        // (e.g. user-content/) that GSD does not manage.
        //
        // For prefix='gsd-' (others): _removeGsdEntries removes only gsd-* entries.
        // Non-gsd-* user dirs (e.g. my-custom-skill/) are untouched. Only preserve the
        // explicit user-owned GSD-prefixed skill gsd-dev-preferences, which GSD does not
        // reinstall from source but must survive the prune (#2973).
        const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>

        if (kind.prefix === '') {
          // Hermes: wipes entire dest dir — preserve anything not in staged.
          const stagedNames = fs.existsSync(stagedForCopy)
            ? new Set(fs.readdirSync(stagedForCopy, { withFileTypes: true })
                .filter(e => e.isDirectory()).map(e => e.name))
            : new Set();
          for (const entry of fs.readdirSync(dest, { withFileTypes: true })) {
            if (!entry.isDirectory() || stagedNames.has(entry.name)) continue;
            const snap = _snapshotDir(path.join(dest, entry.name));
            if (snap.size > 0) toPreserve.set(entry.name, snap);
          }
        } else {
          // Non-Hermes: only preserve explicitly user-owned GSD-prefixed skill dirs.
          // gsd-dev-preferences is the sole user-customisable skill in this category.
          const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
          for (const dirName of USER_OWNED_SKILL_DIRS) {
            const skillDir = path.join(dest, dirName);
            if (!fs.existsSync(skillDir)) continue;
            const snap = _snapshotDir(skillDir);
            if (snap.size > 0) toPreserve.set(dirName, snap);
          }
        }

        _removeGsdEntries(dest, kind);
        _copyStaged(stagedForCopy, dest, kind);

        // Restore user-owned dirs after the prune+copy
        for (const [dirName, snap] of toPreserve) {
          _restoreDir(path.join(dest, dirName), snap);
        }
      } else {
        // For non-skills kinds (commands, agents): no user content to preserve;
        // just prune stale gsd-* entries and copy new ones.
        _removeGsdEntries(dest, kind);
        _copyStaged(stagedForCopy, dest, kind);
      }
    } finally {
      if (tempToClean) {
        try { fs.rmSync(tempToClean, { recursive: true, force: true }); } catch { /* best-effort */ }
      }
    }
  }
}

/**
 * Install the skills layout kind for an OpenCode-family runtime (OpenCode/Kilo).
 *
 * These runtimes do NOT go through installRuntimeArtifacts (their commands use a
 * bespoke flattened-command writer), so this writes ONLY the skills kind
 * alongside their existing command/ + agents/ surfaces. Uninstall is already
 * layout-driven (uninstallRuntimeArtifacts iterates layout.kinds), so the
 * skills/ dir is cleaned up automatically once the layout declares it.
 *
 * `rawCommandsDir` MUST be the SAME staged command directory the flattened
 * command writer consumes (the caller passes its `_stageSkills()` output) so the
 * command/ and skills/ surfaces always cover the identical, profile-resolved set
 * — including the `--minimal`/`--core-only` alias path, which stages differently
 * from a plain `--profile=core`.
 *
 * Mirrors copyFlattenedCommands exactly per file — pathPrefix rewrite →
 * attribution → command→skill conversion — guaranteeing command/ and skills/
 * bodies match byte-for-byte for global, --local, and --config-dir installs.
 * We deliberately do NOT use skillsKindEntry.stage(): that converts before any
 * pathPrefix is known, so its bodies would carry the converter's hardcoded
 * default config dir. (#784)
 *
 * @param {string} runtime - 'opencode' or 'kilo'
 * @param {string} targetDir - resolved runtime config directory
 * @param {string} rawCommandsDir - staged RAW Claude command dir (caller's _stageSkills output)
 * @param {string} pathPrefix - computed config-path prefix for body rewrites
 * @returns {number} number of gsd-* skill directories written
 */
function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPrefix) {
  const layout = resolveRuntimeArtifactLayout(runtime, targetDir);
  const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
  if (!skillsKindEntry) return 0;
  const rawDir = rawCommandsDir;
  if (!rawDir || !fs.existsSync(rawDir)) return 0;

  const converter = runtime === 'kilo'
    ? convertClaudeCommandToKiloSkill
    : convertClaudeCommandToOpencodeSkill;

  const dest = path.join(targetDir, skillsKindEntry.destSubpath);
  fs.mkdirSync(dest, { recursive: true });

  // Preserve user-owned GSD-prefixed skill dirs across the gsd-* prune.
  // gsd-dev-preferences is generated by the user (via generate-dev-preferences)
  // and lives at <configDir>/skills/gsd-dev-preferences — _removeGsdEntries
  // would otherwise wipe it. Mirrors the preservation in installRuntimeArtifacts
  // (#2973).
  const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
  const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
  for (const dirName of USER_OWNED_SKILL_DIRS) {
    const skillDir = path.join(dest, dirName);
    if (!fs.existsSync(skillDir)) continue;
    const snap = _snapshotDir(skillDir);
    if (snap.size > 0) toPreserve.set(dirName, snap);
  }

  _removeGsdEntries(dest, skillsKindEntry);

  let count = 0;
  for (const entry of fs.readdirSync(rawDir, { withFileTypes: true })) {
    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
    const stem = entry.name.slice(0, -3);
    const skillName = `${skillsKindEntry.prefix}${stem}`;
    let content = fs.readFileSync(path.join(rawDir, entry.name), 'utf8');
    content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
    content = processAttribution(content, getCommitAttribution(runtime));
    content = converter(content, skillName);
    const skillDir = path.join(dest, skillName);
    fs.mkdirSync(skillDir, { recursive: true });
    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
    count++;
  }

  // Restore user-owned dirs after the prune+copy.
  for (const [dirName, snap] of toPreserve) {
    _restoreDir(path.join(dest, dirName), snap);
  }

  return count;
}

/**
 * Layout-driven uninstall orchestrator.
 * Runs legacy cleanup first, then uses resolveRuntimeArtifactLayout to
 * determine which GSD-owned entries to remove.
 *
 * @param {string} runtime             canonical runtime ID
 * @param {string} configDir           resolved runtime config directory
 * @param {'global'|'local'} scope
 */
function uninstallRuntimeArtifacts(runtime, configDir, scope) {
  // Legacy cleanup before layout-driven removal (scope-aware to avoid
  // removing Claude local commands/gsd/ which is the primary install dir).
  // Returns saved user artifacts so we can migrate AFTER layout removal
  // (the layout's gsd-* prefix pass would wipe a skill dir created here).
  const savedLegacyArtifacts = _runLegacyUninstallCleanup(runtime, configDir, scope);

  const layout = resolveRuntimeArtifactLayout(runtime, configDir, scope);
  for (const kind of layout.kinds) {
    const dest = path.join(layout.configDir, kind.destSubpath);
    _removeGsdEntries(dest, kind);
  }

  // #2973 / Codex review (bd1f06c9): migrate dev-preferences.md to the
  // runtime-aware SKILL.md location after all layout-driven removal is
  // complete. Do NOT restore to commands/gsd/ — the user is uninstalling.
  if (savedLegacyArtifacts) {
    migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
  }
}

/**
 * Recursively copy directory, replacing paths in .md files
 * Deletes existing destDir first to remove orphaned files from previous versions
 * @param {string} srcDir - Source directory
 * @param {string} destDir - Destination directory
 * @param {string} pathPrefix - Path prefix for file references
 * @param {string} runtime - Target runtime ('claude', 'opencode', 'gemini', 'codex')
 * @param {boolean} isCommand - Whether the source is a command directory
 * @param {boolean} isGlobal - Whether the install is global
 */
function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false, isGlobal = false) {
  const isOpencode = runtime === 'opencode';
  const isKilo = runtime === 'kilo';
  const isGemini = runtime === 'gemini';
  const isCodex = runtime === 'codex';
  const isCopilot = runtime === 'copilot';
  const isAntigravity = runtime === 'antigravity';
  const isCursor = runtime === 'cursor';
  const isWindsurf = runtime === 'windsurf';
  const isAugment = runtime === 'augment';
  const isTrae = runtime === 'trae';
  const isQwen = runtime === 'qwen';
  const isHermes = runtime === 'hermes';
  const isCline = runtime === 'cline';
  const dirName = getDirName(runtime);

  // Clean install: remove existing destination to prevent orphaned files
  if (fs.existsSync(destDir)) {
    fs.rmSync(destDir, { recursive: true });
  }
  fs.mkdirSync(destDir, { recursive: true });

  const entries = fs.readdirSync(srcDir, { withFileTypes: true });

  for (const entry of entries) {
    const srcPath = path.join(srcDir, entry.name);
    const destPath = path.join(destDir, entry.name);

    if (entry.isDirectory()) {
      copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand, isGlobal);
    } else if (entry.name.endsWith('.md')) {
      // Replace ~/.claude/ and $HOME/.claude/ and ./.claude/ with runtime-appropriate paths
      // Skip generic replacement for Copilot — convertClaudeToCopilotContent handles all paths
      let content = fs.readFileSync(srcPath, 'utf8');
      if (!isCopilot && !isAntigravity) {
        const globalClaudeRegex = /~\/\.claude\//g;
        const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
        const localClaudeRegex = /\.\/\.claude\//g;
        content = content.replace(globalClaudeRegex, pathPrefix);
        content = content.replace(globalClaudeHomeRegex, pathPrefix);
        content = content.replace(localClaudeRegex, `./${dirName}/`);
        content = content.replace(/~\/\.claude\b/g, pathPrefix.replace(/\/$/, ''));
        content = content.replace(/\$HOME\/\.claude\b/g, pathPrefix.replace(/\/$/, ''));
        content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
        content = content.replace(/~\/\.qwen\//g, pathPrefix);
        content = content.replace(/\$HOME\/\.qwen\//g, pathPrefix);
        content = content.replace(/\.\/\.qwen\//g, `./${dirName}/`);
        content = content.replace(/~\/\.hermes\//g, pathPrefix);
        content = content.replace(/\$HOME\/\.hermes\//g, pathPrefix);
        content = content.replace(/\.\/\.hermes\//g, `./${dirName}/`);
      }
      content = processAttribution(content, getCommitAttribution(runtime));

      // #3683 — normalize /gsd:<cmd> → /gsd-<cmd> in any body passing through
      // copyWithPathReplacement for runtimes that register commands under the
      // hyphen form; normalizeAgentBodyForRuntime self-gates on
      // shouldNormalizeHyphenNamespaceInAgentBody(runtime) and is a no-op for
      // colon-canonical runtimes (Gemini).
      content = normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames());

      // Convert frontmatter for opencode compatibility
      if (isOpencode || isKilo) {
        content = isKilo
          ? convertClaudeToKiloFrontmatter(content)
          : convertClaudeToOpencodeFrontmatter(content);
        fs.writeFileSync(destPath, content);
      } else if (isGemini) {
        // Apply Gemini-specific Markdown transformations (slash commands, TOML).
        // #778: thread the command name (file stem) so per-command TOML
        // enrichment (live-state injection) can target a specific command.
        const geminiCommandName = isCommand ? entry.name.replace(/\.md$/, '') : null;
        const processed = convertClaudeToGeminiMarkdown(content, { isCommand, commandName: geminiCommandName });
        const finalPath = isCommand ? destPath.replace(/\.md$/, '.toml') : destPath;
        fs.writeFileSync(finalPath, processed);
      } else if (isCodex) {
        content = convertClaudeToCodexMarkdown(content);
        fs.writeFileSync(destPath, content);
      } else if (isCopilot) {
        content = convertClaudeToCopilotContent(content, isGlobal);
        content = processAttribution(content, getCommitAttribution(runtime));
        fs.writeFileSync(destPath, content);
      } else if (isAntigravity) {
        content = convertClaudeToAntigravityContent(content, isGlobal);
        content = processAttribution(content, getCommitAttribution(runtime));
        fs.writeFileSync(destPath, content);
      } else if (isCursor) {
        content = convertClaudeToCursorMarkdown(content);
        fs.writeFileSync(destPath, content);
      } else if (isWindsurf) {
        content = convertClaudeToWindsurfMarkdown(content);
        fs.writeFileSync(destPath, content);
      } else if (isTrae) {
        content = convertClaudeToTraeMarkdown(content);
        fs.writeFileSync(destPath, content);
      } else if (isCline) {
        content = convertClaudeToCliineMarkdown(content);
        fs.writeFileSync(destPath, content);
      } else if (isQwen) {
        content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
        content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
        content = content.replace(/\.claude\//g, '.qwen/');
        fs.writeFileSync(destPath, content);
      } else if (isHermes) {
        content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
        content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
        content = content.replace(/\.claude\//g, '.hermes/');
        fs.writeFileSync(destPath, content);
      } else {
        fs.writeFileSync(destPath, content);
      }
    } else if (isCopilot && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      // Copilot: also transform .cjs/.js files for CONV-06 and CONV-07
      let content = fs.readFileSync(srcPath, 'utf8');
      content = convertClaudeToCopilotContent(content, isGlobal);
      fs.writeFileSync(destPath, content);
    } else if (isAntigravity && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      // Antigravity: also transform .cjs/.js files for path/command conversions
      let content = fs.readFileSync(srcPath, 'utf8');
      content = convertClaudeToAntigravityContent(content, isGlobal);
      fs.writeFileSync(destPath, content);
    } else if (isCursor && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      // For Cursor, also convert Claude references in JS/CJS utility scripts
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/gsd:/gi, 'gsd-');
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.cursor/skills/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, '.cursor/rules/');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Cursor');
      fs.writeFileSync(destPath, jsContent);
    } else if (isWindsurf && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      // For Windsurf, also convert Claude references in JS/CJS utility scripts
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/gsd:/gi, 'gsd-');
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.windsurf/skills/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, '.windsurf/rules');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Windsurf');
      fs.writeFileSync(destPath, jsContent);
    } else if (isTrae && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
        return `/gsd-${commandName}`;
      });
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.trae/skills/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, '.trae/rules/');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Trae');
      fs.writeFileSync(destPath, jsContent);
    } else if (isCline && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.cline/skills/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, '.clinerules');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Cline');
      fs.writeFileSync(destPath, jsContent);
    } else if (isQwen && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.qwen/skills/');
      jsContent = jsContent.replace(/\.claude\//g, '.qwen/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, 'QWEN.md');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Qwen Code');
      fs.writeFileSync(destPath, jsContent);
    } else if (isHermes && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
      let jsContent = fs.readFileSync(srcPath, 'utf8');
      jsContent = jsContent.replace(/\.claude\/skills\//g, '.hermes/skills/');
      jsContent = jsContent.replace(/\.claude\//g, '.hermes/');
      jsContent = jsContent.replace(/CLAUDE\.md/g, 'HERMES.md');
      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Hermes Agent');
      fs.writeFileSync(destPath, jsContent);
    } else {
      fs.copyFileSync(srcPath, destPath);
    }
  }
}

/**
 * Clean up orphaned hook registrations from settings.json
 */
function cleanupOrphanedHooks(settings) {
  const orphanedHookPatterns = [
    'gsd-notify.sh',  // Removed in v1.6.x
    'hooks/statusline.js',  // Renamed to gsd-statusline.js in v1.9.0
    'gsd-intel-index.js',  // Removed in v1.9.2
    'gsd-intel-session.js',  // Removed in v1.9.2
    'gsd-intel-prune.js',  // Removed in v1.9.2
  ];

  let cleanedHooks = false;

  // Check all hook event types (Stop, SessionStart, etc.)
  if (settings.hooks) {
    for (const eventType of Object.keys(settings.hooks)) {
      const hookEntries = settings.hooks[eventType];
      if (Array.isArray(hookEntries)) {
        // Filter out entries that contain orphaned hooks
        const filtered = hookEntries.filter(entry => {
          if (entry.hooks && Array.isArray(entry.hooks)) {
            // Check if any hook in this entry matches orphaned patterns
            const hasOrphaned = entry.hooks.some(h =>
              h.command && orphanedHookPatterns.some(pattern => h.command.includes(pattern))
            );
            if (hasOrphaned) {
              cleanedHooks = true;
              return false;  // Remove this entry
            }
          }
          return true;  // Keep this entry
        });
        settings.hooks[eventType] = filtered;
      }
    }
  }

  if (cleanedHooks) {
    console.log(`  ${green}✓${reset} Removed orphaned hook registrations`);
  }

  // Fix #330: Update statusLine if it points to old GSD statusline.js path
  // Only match the specific old GSD path pattern (hooks/statusline.js),
  // not third-party statusline scripts that happen to contain 'statusline.js'
  if (settings.statusLine && settings.statusLine.command &&
    /hooks[\/\\]statusline\.js/.test(settings.statusLine.command)) {
    settings.statusLine.command = settings.statusLine.command.replace(
      /hooks([\/\\])statusline\.js/,
      'hooks$1gsd-statusline.js'
    );
    console.log(`  ${green}✓${reset} Updated statusline path (hooks/statusline.js → hooks/gsd-statusline.js)`);
  }

  return settings;
}

/**
 * Validate hook field requirements to prevent silent settings.json rejection.
 *
 * Claude Code validates the entire settings file with a strict Zod schema.
 * If ANY hook has an invalid schema (e.g., type: "agent" missing "prompt"),
 * the ENTIRE settings.json is silently discarded — disabling all plugins,
 * env vars, and other configuration.
 *
 * This defensive check removes invalid hook entries and cleans up empty
 * event arrays to prevent this. It validates:
 *   - agent hooks require a "prompt" field
 *   - command hooks require a "command" field
 *   - entries must have a valid "hooks" array (non-array/missing is removed)
 *
 * @param {object} settings - The settings object (mutated in place)
 * @returns {object} The same settings object
 */
function validateHookFields(settings) {
  if (!settings.hooks || typeof settings.hooks !== 'object') return settings;

  let fixedHooks = false;
  const emptyKeys = [];

  for (const [eventType, hookEntries] of Object.entries(settings.hooks)) {
    if (!Array.isArray(hookEntries)) continue;

    // Pass 1: validate each entry, building a new array without mutation
    const validated = [];
    for (const entry of hookEntries) {
      // Entries without a hooks sub-array are structurally invalid — remove them
      if (!entry.hooks || !Array.isArray(entry.hooks)) {
        fixedHooks = true;
        continue;
      }

      // Filter invalid hooks within the entry
      const validHooks = entry.hooks.filter(h => {
        if (h.type === 'agent' && !h.prompt) {
          fixedHooks = true;
          return false;
        }
        if (h.type === 'command' && !h.command) {
          fixedHooks = true;
          return false;
        }
        return true;
      });

      // Drop entries whose hooks are now empty
      if (validHooks.length === 0) {
        fixedHooks = true;
        continue;
      }

      // Build a clean copy instead of mutating the original entry
      validated.push({ ...entry, hooks: validHooks });
    }

    settings.hooks[eventType] = validated;

    // Collect empty event arrays for removal (avoid delete during iteration)
    if (validated.length === 0) {
      emptyKeys.push(eventType);
      fixedHooks = true;
    }
  }

  // Pass 2: remove empty event arrays
  for (const key of emptyKeys) {
    delete settings.hooks[key];
  }

  if (fixedHooks) {
    console.log(`  ${green}✓${reset} Fixed invalid hook entries (prevents settings.json schema rejection)`);
  }

  return settings;
}

/**
 * GSD hook filenames removed during uninstall.
 * Module-level so tests can assert structurally instead of regex-parsing source
 * (retires pending-migration-to-typed-ir on hooks-opt-in.test.cjs, per #455).
 */
const GSD_UNINSTALL_HOOKS = [
  'gsd-statusline.js',
  'gsd-check-update.js',
  'gsd-check-update.cmd',
  'gsd-config-reload.js',
  'gsd-context-monitor.js',
  'gsd-cursor-session-start.js',
  'gsd-cursor-post-tool.js',
  'gsd-prompt-guard.js',
  'gsd-read-guard.js',
  'gsd-read-injection-scanner.js',
  'gsd-update-banner.js',
  'gsd-workflow-guard.js',
  'gsd-session-state.sh',
  'gsd-validate-commit.sh',
  'gsd-phase-boundary.sh',
  'gsd-graphify-update.sh',
];

/**
 * Uninstall GSD from the specified directory for a specific runtime
 * Removes only GSD-specific files/directories, preserves user content
 * @param {boolean} isGlobal - Whether to uninstall from global or local
 * @param {string} runtime - Target runtime ('claude', 'opencode', 'gemini', 'codex', 'copilot')
 */
function uninstall(isGlobal, runtime = 'claude') {
  const isOpencode = runtime === 'opencode';
  const isKilo = runtime === 'kilo';
  const isGemini = runtime === 'gemini';
  const isCodex = runtime === 'codex';
  const isCopilot = runtime === 'copilot';
  const isAntigravity = runtime === 'antigravity';
  const isCursor = runtime === 'cursor';
  const isWindsurf = runtime === 'windsurf';
  const isAugment = runtime === 'augment';
  const isTrae = runtime === 'trae';
  const isQwen = runtime === 'qwen';
  const isHermes = runtime === 'hermes';
  const isCodebuddy = runtime === 'codebuddy';
  const dirName = getDirName(runtime);

  // Get the target directory based on runtime and install type. Cline local
  // installs write to the project root (.clinerules/ lives at the root, not in
  // a .cline/ subdir), mirroring the install() path resolution (#787).
  const targetDir = isGlobal
    ? getGlobalConfigDir(runtime, explicitConfigDir)
    : runtime === 'cline'
      ? process.cwd()
      : path.join(process.cwd(), dirName);

  const locationLabel = isGlobal
    ? targetDir.replace(os.homedir(), '~')
    : targetDir.replace(process.cwd(), '.');

  let runtimeLabel = 'Claude Code';
  if (runtime === 'opencode') runtimeLabel = 'OpenCode';
  if (runtime === 'gemini') runtimeLabel = 'Gemini';
  if (runtime === 'kilo') runtimeLabel = 'Kilo';
  if (runtime === 'codex') runtimeLabel = 'Codex';
  if (runtime === 'copilot') runtimeLabel = 'Copilot';
  if (runtime === 'antigravity') runtimeLabel = 'Antigravity';
  if (runtime === 'cursor') runtimeLabel = 'Cursor';
  if (runtime === 'windsurf') runtimeLabel = 'Windsurf';
  if (runtime === 'augment') runtimeLabel = 'Augment';
  if (runtime === 'trae') runtimeLabel = 'Trae';
  if (runtime === 'qwen') runtimeLabel = 'Qwen Code';
  if (runtime === 'hermes') runtimeLabel = 'Hermes Agent';
  if (runtime === 'kimi') runtimeLabel = 'Kimi CLI';
  if (runtime === 'codebuddy') runtimeLabel = 'CodeBuddy';

  console.log(`  Uninstalling GSD from ${cyan}${runtimeLabel}${reset} at ${cyan}${locationLabel}${reset}\n`);

  // #786: AGENTS.md lives at the repo root (outside targetDir) for local Copilot
  // installs, so its cleanup must run even when .github (targetDir) was already
  // removed — i.e. BEFORE the "target directory missing" early-return below.
  if (isCopilot && !isGlobal) {
    const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
    if (fs.existsSync(agentsMdPath)) {
      const content = fs.readFileSync(agentsMdPath, 'utf8');
      const cleaned = stripGsdFromCopilotInstructions(content);
      if (cleaned === null) {
        fs.unlinkSync(agentsMdPath);
        console.log(`  ${green}✓${reset} Removed AGENTS.md (was GSD-only)`);
      } else if (cleaned !== content) {
        fs.writeFileSync(agentsMdPath, cleaned);
        console.log(`  ${green}✓${reset} Cleaned GSD section from AGENTS.md`);
      }
    }
  }

  // Check if target directory exists
  if (!fs.existsSync(targetDir)) {
    console.log(`  ${yellow}⚠${reset} Directory does not exist: ${locationLabel}`);
    console.log(`  Nothing to uninstall.\n`);
    return;
  }

  let removedCount = 0;

  // Remove profile marker so a clean reinstall defaults to full surface.
  try {
    fs.unlinkSync(path.join(targetDir, '.gsd-profile'));
    removedCount++;
  } catch {}

  // 1. Remove GSD commands/skills (layout-driven)
  const scope = isGlobal ? 'global' : 'local';
  uninstallRuntimeArtifacts(runtime, targetDir, scope);
  removedCount++;

  // 1a. Non-layout Codex side-effects: agent .toml files, config.toml sections, hooks.json
  if (isCodex) {
    const codexAgentsDir = path.join(targetDir, 'agents');
    if (fs.existsSync(codexAgentsDir)) {
      const tomlFiles = fs.readdirSync(codexAgentsDir);
      let tomlCount = 0;
      for (const file of tomlFiles) {
        if (file.startsWith('gsd-') && file.endsWith('.toml')) {
          fs.unlinkSync(path.join(codexAgentsDir, file));
          tomlCount++;
        }
      }
      if (tomlCount > 0) {
        removedCount++;
        console.log(`  ${green}✓${reset} Removed ${tomlCount} agent .toml configs`);
      }
    }

    // Codex: clean GSD sections from config.toml
    const codexConfigPath = path.join(targetDir, 'config.toml');
    if (fs.existsSync(codexConfigPath)) {
      const content = fs.readFileSync(codexConfigPath, 'utf8');
      const cleaned = stripGsdFromCodexConfig(content);
      if (cleaned === null) {
        fs.unlinkSync(codexConfigPath);
        removedCount++;
        console.log(`  ${green}✓${reset} Removed config.toml (was GSD-only)`);
      } else if (cleaned !== content) {
        fs.writeFileSync(codexConfigPath, cleaned);
        removedCount++;
        console.log(`  ${green}✓${reset} Cleaned GSD sections from config.toml`);
      }
    }

    const hooksJsonCleanup = removeCodexHooksJsonSessionStart(targetDir);
    if (hooksJsonCleanup.changed) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed managed Codex SessionStart hook from hooks.json`);
    }

    // #772: remove new Codex hook event registrations added by this enhancement.
    for (const eventName of ['SubagentStart', 'Stop', 'PostToolUse']) {
      const eventCleanup = removeCodexHooksJsonEvent(targetDir, eventName);
      if (eventCleanup.changed) {
        removedCount++;
        console.log(`  ${green}✓${reset} Removed managed Codex ${eventName} hook from hooks.json`);
      }
    }
  }

  // 1b. Non-layout Copilot side-effect: copilot-instructions.md cleanup
  if (isCopilot) {
    const instructionsPath = path.join(targetDir, 'copilot-instructions.md');
    if (fs.existsSync(instructionsPath)) {
      const content = fs.readFileSync(instructionsPath, 'utf8');
      const cleaned = stripGsdFromCopilotInstructions(content);
      if (cleaned === null) {
        fs.unlinkSync(instructionsPath);
        removedCount++;
        console.log(`  ${green}✓${reset} Removed copilot-instructions.md (was GSD-only)`);
      } else if (cleaned !== content) {
        fs.writeFileSync(instructionsPath, cleaned);
        removedCount++;
        console.log(`  ${green}✓${reset} Cleaned GSD section from copilot-instructions.md`);
      }
    }

    // #786: remove the GSD-managed Copilot lifecycle hook config and prune the
    // hooks dir if we left it empty.
    const hookPath = path.join(targetDir, 'hooks', GSD_COPILOT_HOOK_FILE);
    if (fs.existsSync(hookPath)) {
      fs.unlinkSync(hookPath);
      removedCount++;
      console.log(`  ${green}✓${reset} Removed Copilot lifecycle hook (${GSD_COPILOT_HOOK_FILE})`);
      try {
        const hooksDir = path.join(targetDir, 'hooks');
        if (fs.existsSync(hooksDir) && fs.readdirSync(hooksDir).length === 0) {
          fs.rmdirSync(hooksDir);
        }
      } catch { /* non-fatal: leave a non-empty/locked hooks dir in place */ }
    }
    // Note: AGENTS.md (repo root) is cleaned earlier, before the targetDir
    // existence early-return, since it lives outside targetDir (#786).
  }

  // 1b-cline. Non-layout Cline side-effects (issue #787): remove the
  // directory-form rules + PreToolUse hook, and strip the GSD block from the
  // global cross-tool ~/.agents/AGENTS.md target.
  if (runtime === 'cline') {
    const clinerulesDir = path.join(targetDir, '.clinerules');
    for (const rel of ['gsd.md', path.join('hooks', 'PreToolUse')]) {
      const p = path.join(clinerulesDir, rel);
      try {
        if (fs.existsSync(p)) {
          fs.unlinkSync(p);
          removedCount++;
        }
      } catch { /* best-effort */ }
    }
    // Also remove a legacy single-file .clinerules left by pre-#787 installs.
    try {
      if (fs.existsSync(clinerulesDir) && fs.statSync(clinerulesDir).isFile()) {
        fs.unlinkSync(clinerulesDir);
        removedCount++;
      }
    } catch { /* best-effort */ }
    // Prune now-empty GSD-created directories (leave any user-added rule files).
    for (const dir of [path.join(clinerulesDir, 'hooks'), clinerulesDir]) {
      try {
        if (fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0) {
          fs.rmdirSync(dir);
        }
      } catch { /* best-effort */ }
    }
    if (isGlobal) {
      const agentsPath = path.join(os.homedir(), '.agents', 'AGENTS.md');
      try {
        if (fs.existsSync(agentsPath)) {
          const content = fs.readFileSync(agentsPath, 'utf8');
          const cleaned = stripGsdFromAgentsMd(content);
          if (cleaned === null) {
            fs.unlinkSync(agentsPath);
            removedCount++;
            console.log(`  ${green}✓${reset} Removed ~/.agents/AGENTS.md (was GSD-only)`);
          } else if (cleaned !== content) {
            fs.writeFileSync(agentsPath, cleaned);
            removedCount++;
            console.log(`  ${green}✓${reset} Cleaned GSD section from ~/.agents/AGENTS.md`);
          }
        }
      } catch { /* best-effort */ }
    }
  }

  // 1b-cursor. Non-layout Cursor side-effects (issue #777): remove GSD-managed
  // hook entries from hooks.json and clean up the managed hook scripts.
  if (isCursor) {
    const hooksJsonCleanup = removeCursorHooksJson(targetDir);
    if (hooksJsonCleanup.changed) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed GSD-managed Cursor hooks from hooks.json`);
    }
    // Remove the managed hook scripts (session-start + post-tool).
    const hooksDir = path.join(targetDir, 'hooks');
    for (const script of [GSD_CURSOR_SESSION_HOOK_SCRIPT, GSD_CURSOR_POST_TOOL_HOOK_SCRIPT]) {
      const p = path.join(hooksDir, script);
      try {
        if (fs.existsSync(p)) {
          fs.unlinkSync(p);
          removedCount++;
        }
      } catch { /* best-effort */ }
    }
    // Prune hooks/ if empty.
    try {
      if (fs.existsSync(hooksDir) && fs.readdirSync(hooksDir).length === 0) {
        fs.rmdirSync(hooksDir);
      }
    } catch { /* best-effort */ }
  }

  // 1c. Claude local: remove commands/gsd/ (primary local install location).
  //     The layout's _removeGsdEntries uses the 'gsd-' prefix which applies to
  //     flat command dirs (OpenCode/Kilo). Claude local files use no prefix inside
  //     the namespaced directory, so layout does not remove them. Handle inline.
  //     Preserve dev-preferences.md across the wipe (#1423).
  if (!isGlobal && runtime === 'claude') {
    const gsdCommandsDir = path.join(targetDir, 'commands', 'gsd');
    if (fs.existsSync(gsdCommandsDir)) {
      const devPrefsPath = path.join(gsdCommandsDir, 'dev-preferences.md');
      const preservedDevPrefs = fs.existsSync(devPrefsPath) ? fs.readFileSync(devPrefsPath, 'utf-8') : null;
      fs.rmSync(gsdCommandsDir, { recursive: true });
      removedCount++;
      console.log(`  ${green}✓${reset} Removed commands/gsd/`);
      if (preservedDevPrefs) {
        try {
          fs.mkdirSync(gsdCommandsDir, { recursive: true });
          fs.writeFileSync(devPrefsPath, preservedDevPrefs);
          console.log(`  ${green}✓${reset} Preserved commands/gsd/dev-preferences.md`);
        } catch (err) {
          console.error(`  ${red}✗${reset} Failed to restore dev-preferences.md: ${err.message}`);
        }
      }
    }
  }

  // 1d. Gemini: remove commands/gsd/ with dev-preferences.md preservation.
  //     The layout removes gsd-*.toml files but not the directory itself.
  //     Preserve user files before removing the directory.
  if (isGemini) {
    const gsdCommandsDir = path.join(targetDir, 'commands', 'gsd');
    if (fs.existsSync(gsdCommandsDir)) {
      const devPrefsPath = path.join(gsdCommandsDir, 'dev-preferences.md');
      const preservedDevPrefs = fs.existsSync(devPrefsPath) ? fs.readFileSync(devPrefsPath, 'utf-8') : null;
      fs.rmSync(gsdCommandsDir, { recursive: true });
      removedCount++;
      console.log(`  ${green}✓${reset} Removed commands/gsd/`);
      if (preservedDevPrefs) {
        try {
          fs.mkdirSync(gsdCommandsDir, { recursive: true });
          fs.writeFileSync(devPrefsPath, preservedDevPrefs);
          console.log(`  ${green}✓${reset} Preserved commands/gsd/dev-preferences.md`);
        } catch (err) {
          console.error(`  ${red}✗${reset} Failed to restore dev-preferences.md: ${err.message}`);
        }
      }
    }
  }

  // 1d. Qwen/Hermes: migrate dev-preferences.md from legacy commands/gsd/ location
  //     during uninstall. _runLegacyUninstallCleanup (called by uninstallRuntimeArtifacts)
  //     removes the directory; we must preserve/restore user artifacts before that path.
  //     This block runs AFTER uninstallRuntimeArtifacts, so we check if the directory
  //     was already removed and skip if so (idempotent).
  if (isQwen || isHermes) {
    // dev-preferences may have survived in skills/ as SKILL.md — nothing to do for
    // that case. If a stale commands/gsd/ still exists (e.g. legacy was not removed),
    // attempt migration. In practice _runLegacyUninstallCleanup removes it first,
    // so this is a best-effort guard.
    const legacyDir = path.join(targetDir, 'commands', 'gsd');
    if (fs.existsSync(legacyDir)) {
      const savedLegacyArtifacts = preserveUserArtifacts(legacyDir, ['dev-preferences.md']);
      fs.rmSync(legacyDir, { recursive: true });
      removedCount++;
      console.log(`  ${green}✓${reset} Removed legacy commands/gsd/`);
      const _uninstallScope = isGlobal ? 'global' : 'local';
      if (migrateLegacyDevPreferencesToSkill(targetDir, savedLegacyArtifacts, runtime, _uninstallScope)) {
        // Compute the actual path written so the log line is accurate per-runtime
        const _layout = resolveRuntimeArtifactLayout(runtime, targetDir, _uninstallScope);
        const _sk = _layout.kinds.find((k) => k.kind === 'skills');
        const _stem = _sk && _sk.prefix === '' ? 'dev-preferences' : 'gsd-dev-preferences';
        const _skillRelPath = _sk ? `${_sk.destSubpath}/${_stem}/SKILL.md` : 'skills/gsd-dev-preferences/SKILL.md';
        console.log(`  ${green}✓${reset} Migrated dev-preferences.md → ${_skillRelPath} (#2973)`);
      } else {
        // Migration failed or already exists — restore to legacy location so user content is not lost
        restoreUserArtifacts(legacyDir, savedLegacyArtifacts);
      }
    }
  }

  // 2. Remove gsd-core directory
  const gsdDir = path.join(targetDir, 'gsd-core');
  if (fs.existsSync(gsdDir)) {
    // Preserve user-generated files before wipe (#1423)
    const userProfilePath = path.join(gsdDir, 'USER-PROFILE.md');
    const preservedProfile = fs.existsSync(userProfilePath) ? fs.readFileSync(userProfilePath, 'utf-8') : null;

    fs.rmSync(gsdDir, { recursive: true });
    removedCount++;
    console.log(`  ${green}✓${reset} Removed gsd-core/`);

    // Restore user-generated files
    if (preservedProfile) {
      try {
        fs.mkdirSync(gsdDir, { recursive: true });
        fs.writeFileSync(userProfilePath, preservedProfile);
        console.log(`  ${green}✓${reset} Preserved gsd-core/USER-PROFILE.md`);
      } catch (err) {
        console.error(`  ${red}✗${reset} Failed to restore USER-PROFILE.md: ${err.message}`);
      }
    }
  }

  // 3. Remove GSD agents (gsd-*.md files only)
  const agentsDir = path.join(targetDir, 'agents');
  if (fs.existsSync(agentsDir)) {
    const files = fs.readdirSync(agentsDir);
    let agentCount = 0;
    for (const file of files) {
      if (file.startsWith('gsd-') && file.endsWith('.md')) {
        fs.unlinkSync(path.join(agentsDir, file));
        agentCount++;
      }
    }
    if (agentCount > 0) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed ${agentCount} GSD agents`);
    }
  }

  // 4. Remove GSD hooks
  const hooksDir = path.join(targetDir, 'hooks');
  if (fs.existsSync(hooksDir)) {
    let hookCount = 0;
    for (const hook of GSD_UNINSTALL_HOOKS) {
      const hookPath = path.join(hooksDir, hook);
      if (fs.existsSync(hookPath)) {
        fs.unlinkSync(hookPath);
        hookCount++;
      }
    }
    if (hookCount > 0) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed ${hookCount} GSD hooks`);
    }

    // Remove only the GSD-managed files from hooks/lib/ (git-cmd.js + gsd-graphify-rebuild.sh).
    // hooks/lib/ lives inside the user's runtime hooks directory (shared space) and
    // may contain user-owned custom helpers. We must not recursively delete the dir.
    const hooksLibDir = path.join(hooksDir, 'lib');
    if (fs.existsSync(hooksLibDir)) {
      let removedLibFiles = 0;
      for (const file of GSD_HOOK_LIB_FILES) {
        const filePath = path.join(hooksLibDir, file);
        try {
          fs.unlinkSync(filePath);
          removedLibFiles++;
        } catch (_) {
          // Ignore missing files (best effort, non-fatal)
        }
      }
      // Only remove the directory itself if it is now empty (preserve any user files)
      try {
        fs.rmdirSync(hooksLibDir);
      } catch (_) {
        // Directory not empty or other error — leave it alone
      }
      if (removedLibFiles > 0) {
        removedCount++;
        console.log(`  ${green}✓${reset} Removed ${removedLibFiles} hooks/lib/ helper(s)`);
      }
    }
  }

  // 4a. Remove scripts/changeset/ and scripts/lib/ (#935)
  // GSD-managed files only: enumerate the exact set the installer writes.
  // Any file NOT in this set is user-owned and must survive uninstall.
  // After removing GSD files, attempt to rmdir — if the directory is still
  // non-empty (user has custom helpers) it stays; otherwise it goes cleanly.
  const GSD_CHANGESET_FILES = [
    'cli.cjs', 'parse.cjs', 'render.cjs', 'serialize.cjs',
    'github-release-notes.cjs', 'lint.cjs', 'new.cjs',
    'README.md', // documentation only — not user-authored
  ];
  const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs'];

  const changesetUninstallDir = path.join(targetDir, 'scripts', 'changeset');
  if (fs.existsSync(changesetUninstallDir)) {
    let removedChangeset = 0;
    for (const file of GSD_CHANGESET_FILES) {
      const fp = path.join(changesetUninstallDir, file);
      try { fs.unlinkSync(fp); removedChangeset++; } catch (_) { /* best-effort */ }
    }
    // Remove directory if empty after our cleanup
    try { fs.rmdirSync(changesetUninstallDir); } catch (_) { /* Not empty — user content present */ }
    if (removedChangeset > 0) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed scripts/changeset/ GSD files`);
    }
  }
  const scriptsLibUninstallDir = path.join(targetDir, 'scripts', 'lib');
  if (fs.existsSync(scriptsLibUninstallDir)) {
    let removedScriptsLib = 0;
    for (const file of GSD_SCRIPTS_LIB_FILES) {
      const fp = path.join(scriptsLibUninstallDir, file);
      try { fs.unlinkSync(fp); removedScriptsLib++; } catch (_) { /* best-effort */ }
    }
    // Remove directory if empty after our cleanup
    try { fs.rmdirSync(scriptsLibUninstallDir); } catch (_) { /* Not empty — user content present */ }
    if (removedScriptsLib > 0) {
      removedCount++;
      console.log(`  ${green}✓${reset} Removed scripts/lib/ GSD files`);
    }
  }
  // If scripts/ dir is now empty, remove it too
  const scriptsUninstallDir = path.join(targetDir, 'scripts');
  if (fs.existsSync(scriptsUninstallDir)) {
    try { fs.rmdirSync(scriptsUninstallDir); } catch (_) { /* Not empty — leave it */ }
  }

  // 5. Remove GSD package.json (CommonJS mode marker)
  const pkgJsonPath = path.join(targetDir, 'package.json');
  if (fs.existsSync(pkgJsonPath)) {
    try {
      const content = fs.readFileSync(pkgJsonPath, 'utf8').trim();
      // Only remove if it's our minimal CommonJS marker
      if (content === '{"type":"commonjs"}') {
        fs.unlinkSync(pkgJsonPath);
        removedCount++;
        console.log(`  ${green}✓${reset} Removed GSD package.json`);
      }
    } catch (e) {
      // Ignore read errors
    }
  }

  // 6. Clean up settings.json (remove GSD hooks and statusline)
  const settingsPath = path.join(targetDir, 'settings.json');
  if (fs.existsSync(settingsPath)) {
    let settings = readSettings(settingsPath);
    if (settings === null) {
      console.log(`  ${yellow}i${reset} Skipping settings.json cleanup — file could not be parsed`);
      settings = {}; // prevent downstream crashes, but don't write back
    }
    let settingsModified = false;

    // Remove GSD statusline if it references our hook
    if (settings.statusLine && settings.statusLine.command &&
      settings.statusLine.command.includes('gsd-statusline')) {
      delete settings.statusLine;
      settingsModified = true;
      console.log(`  ${green}✓${reset} Removed GSD statusline from settings`);
    }

    // Remove GSD hooks from settings — per-hook granularity to preserve
    // user hooks that share an entry with a GSD hook (#1755 followup).
    // Includes the 3 Qwen-only events added in #788 (SubagentStop, Stop,
    // PreCompact, also registered for Claude in #770), the 3 Gemini-only
    // events added in #776 (BeforeAgent, AfterAgent, BeforeModel), and the
    // Claude-only FileChanged event added in #770 — safe to iterate for all
    // runtimes; installs that don't register these events simply find no
    // entries and skip.
    for (const eventName of ['SessionStart', 'PostToolUse', 'AfterTool', 'PreToolUse', 'BeforeTool', 'SubagentStop', 'Stop', 'PreCompact', 'BeforeAgent', 'AfterAgent', 'BeforeModel', 'FileChanged']) {
      if (settings.hooks && settings.hooks[eventName]) {
        const before = JSON.stringify(settings.hooks[eventName]);
        settings.hooks[eventName] = settings.hooks[eventName]
          .map(entry => {
            if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return entry;
            // Filter out individual GSD hooks, keep user hooks
            entry.hooks = entry.hooks.filter((h) => {
              if (!h || typeof h.command !== 'string') return true;
              return !isManagedHookCommand(h.command, {
                surface: 'settings-json',
              });
            });
            return entry.hooks.length > 0 ? entry : null;
          })
          .filter(Boolean);
        if (JSON.stringify(settings.hooks[eventName]) !== before) {
          settingsModified = true;
        }
        if (settings.hooks[eventName].length === 0) {
          delete settings.hooks[eventName];
        }
      }
    }
    if (settingsModified) {
      console.log(`  ${green}✓${reset} Removed GSD hooks from settings`);
    }

    // Clean up empty hooks object
    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
      delete settings.hooks;
    }

    // #768 — Remove GSD-owned Claude permissions from settings.json.
    // Applies only to Claude uninstalls. Filter only the exact GSD-owned entries
    // to preserve any user-added allow/deny entries.
    // Uses a local flag to avoid the shared `settingsModified` producing a false
    // "Removed GSD permissions" message when only hooks/statusline changed.
    if (runtime === 'claude' && settings.permissions) {
      let permissionsModified = false;
      if (Array.isArray(settings.permissions.allow)) {
        const before = settings.permissions.allow.length;
        settings.permissions.allow = settings.permissions.allow.filter(
          (e) => !GSD_CLAUDE_ALLOW_PERMISSIONS.includes(e)
        );
        if (settings.permissions.allow.length !== before) {
          permissionsModified = true;
        }
      }
      if (Array.isArray(settings.permissions.deny)) {
        const before = settings.permissions.deny.length;
        settings.permissions.deny = settings.permissions.deny.filter(
          (e) => !GSD_CLAUDE_DENY_PERMISSIONS.includes(e)
        );
        if (settings.permissions.deny.length !== before) {
          permissionsModified = true;
        }
      }
      if (permissionsModified) {
        settingsModified = true;
        console.log(`  ${green}✓${reset} Removed GSD permissions from settings.json`);
      }
    }

    if (settingsModified) {
      writeSettings(settingsPath, settings);
      removedCount++;
    }
  }

  // 6. For OpenCode, clean up permissions from opencode.json or opencode.jsonc
  if (isOpencode) {
    const configPath = resolveOpencodeConfigPath(targetDir);
    if (fs.existsSync(configPath)) {
      try {
        const config = parseJsonc(fs.readFileSync(configPath, 'utf8'));
        let modified = false;

        // Remove GSD permission entries
        if (config.permission) {
          for (const permType of ['read', 'external_directory']) {
            if (config.permission[permType]) {
              const keys = Object.keys(config.permission[permType]);
              for (const key of keys) {
                if (key.includes('gsd-core')) {
                  delete config.permission[permType][key];
                  modified = true;
                }
              }
              // Clean up empty objects
              if (Object.keys(config.permission[permType]).length === 0) {
                delete config.permission[permType];
              }
            }
          }
          if (Object.keys(config.permission).length === 0) {
            delete config.permission;
          }
        }

        if (modified) {
          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
          removedCount++;
          console.log(`  ${green}✓${reset} Removed GSD permissions from ${path.basename(configPath)}`);
        }
      } catch (e) {
        // Ignore JSON parse errors
      }
    }
  }

  // 7. For Kilo, clean up permissions from kilo.json or kilo.jsonc
  if (isKilo) {
    const configPath = resolveKiloConfigPath(targetDir);
    if (fs.existsSync(configPath)) {
      try {
        const config = parseJsonc(fs.readFileSync(configPath, 'utf8'));
        let modified = false;

        // Remove GSD permission entries
        if (config.permission) {
          for (const permType of ['read', 'external_directory']) {
            if (config.permission[permType]) {
              const keys = Object.keys(config.permission[permType]);
              for (const key of keys) {
                if (key.includes('gsd-core')) {
                  delete config.permission[permType][key];
                  modified = true;
                }
              }
              // Clean up empty objects
              if (Object.keys(config.permission[permType]).length === 0) {
                delete config.permission[permType];
              }
            }
          }
          if (Object.keys(config.permission).length === 0) {
            delete config.permission;
          }
        }

        if (modified) {
          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
          removedCount++;
          console.log(`  ${green}✓${reset} Removed GSD permissions from ${path.basename(configPath)}`);
        }
      } catch (e) {
        // Ignore JSON parse errors
      }
    }
  }

  // Remove the file manifest that the installer wrote at install time.
  // Without this step the metadata file persists after uninstall (#1908).
  const manifestPath = path.join(targetDir, MANIFEST_NAME);
  if (fs.existsSync(manifestPath)) {
    fs.rmSync(manifestPath, { force: true });
    removedCount++;
    console.log(`  ${green}✓${reset} Removed ${MANIFEST_NAME}`);
  }

  if (removedCount === 0) {
    console.log(`  ${yellow}⚠${reset} No GSD files found to remove.`);
  }

  console.log(`
  ${green}Done!${reset} GSD has been uninstalled from ${runtimeLabel}.
  Your other files and settings have been preserved.
`);
}

/**
 * Parse JSONC (JSON with Comments) by stripping comments and trailing commas.
 * OpenCode supports JSONC format via jsonc-parser, so users may have comments.
 * This is a lightweight inline parser to avoid adding dependencies.
 */
function parseJsonc(content) {
  // Strip BOM if present
  if (content.charCodeAt(0) === 0xFEFF) {
    content = content.slice(1);
  }

  // Remove single-line and block comments while preserving strings
  let result = '';
  let inString = false;
  let i = 0;
  while (i < content.length) {
    const char = content[i];
    const next = content[i + 1];

    if (inString) {
      result += char;
      // Handle escape sequences
      if (char === '\\' && i + 1 < content.length) {
        result += next;
        i += 2;
        continue;
      }
      if (char === '"') {
        inString = false;
      }
      i++;
    } else {
      if (char === '"') {
        inString = true;
        result += char;
        i++;
      } else if (char === '/' && next === '/') {
        // Skip single-line comment until end of line
        while (i < content.length && content[i] !== '\n') {
          i++;
        }
      } else if (char === '/' && next === '*') {
        // Skip block comment
        i += 2;
        while (i < content.length - 1 && !(content[i] === '*' && content[i + 1] === '/')) {
          i++;
        }
        i += 2; // Skip closing */
      } else {
        result += char;
        i++;
      }
    }
  }

  // Remove trailing commas before } or ]
  result = result.replace(/,(\s*[}\]])/g, '$1');

  return JSON.parse(result);
}

/**
 * Configure OpenCode permissions to allow reading GSD reference docs
 * This prevents permission prompts when GSD accesses the gsd-core directory
 * @param {boolean} isGlobal - Whether this is a global or local install
 * @param {string|null} configDir - Resolved config directory when already known
 */
function configureOpencodePermissions(isGlobal = true, configDir = null) {
  // For local installs, use ./.opencode/
  // For global installs, use ~/.config/opencode/
  const opencodeConfigDir = configDir || (isGlobal
    ? getGlobalConfigDir('opencode', explicitConfigDir)
    : path.join(process.cwd(), '.opencode'));
  // Ensure config directory exists
  fs.mkdirSync(opencodeConfigDir, { recursive: true });

  const configPath = resolveOpencodeConfigPath(opencodeConfigDir);

  // Read existing config or create empty object
  let config = {};
  if (fs.existsSync(configPath)) {
    try {
      const content = fs.readFileSync(configPath, 'utf8');
      config = parseJsonc(content);
    } catch (e) {
      // Cannot parse - DO NOT overwrite user's config
      const configFile = path.basename(configPath);
      console.log(`  ${yellow}⚠${reset} Could not parse ${configFile} - skipping permission config`);
      console.log(`    ${dim}Reason: ${e.message}${reset}`);
      console.log(`    ${dim}Your config was NOT modified. Fix the syntax manually if needed.${reset}`);
      return;
    }
  }

  // OpenCode also allows a top-level string permission like "allow".
  // In that case, path-specific permission entries are unnecessary.
  if (typeof config.permission === 'string') {
    return;
  }

  // Ensure permission structure exists
  if (!config.permission || typeof config.permission !== 'object') {
    config.permission = {};
  }

  // Build the GSD path using the actual config directory
  // Use ~ shorthand if it's in the default location, otherwise use full path
  const defaultConfigDir = path.join(os.homedir(), '.config', 'opencode');
  const gsdPath = opencodeConfigDir === defaultConfigDir
    ? '~/.config/opencode/gsd-core/*'
    : `${opencodeConfigDir.replace(/\\/g, '/')}/gsd-core/*`;

  let modified = false;

  // Configure read permission
  if (!config.permission.read || typeof config.permission.read !== 'object') {
    config.permission.read = {};
  }
  if (config.permission.read[gsdPath] !== 'allow') {
    config.permission.read[gsdPath] = 'allow';
    modified = true;
  }

  // Configure external_directory permission (the safety guard for paths outside project)
  if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
    config.permission.external_directory = {};
  }
  if (config.permission.external_directory[gsdPath] !== 'allow') {
    config.permission.external_directory[gsdPath] = 'allow';
    modified = true;
  }

  if (!modified) {
    return; // Already configured
  }

  // Write config back
  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
  console.log(`  ${green}✓${reset} Configured read permission for GSD docs`);
}

/**
 * Configure Kilo permissions to allow reading GSD reference docs
 * This prevents permission prompts when GSD accesses the gsd-core directory
 * @param {boolean} isGlobal - Whether this is a global or local install
 * @param {string|null} configDir - Resolved config directory when already known
 */
function configureKiloPermissions(isGlobal = true, configDir = null) {
  // For local installs, use ./.kilo/
  // For global installs, use ~/.config/kilo/
  const kiloConfigDir = configDir || (isGlobal
    ? getGlobalConfigDir('kilo', explicitConfigDir)
    : path.join(process.cwd(), '.kilo'));
  // Ensure config directory exists
  fs.mkdirSync(kiloConfigDir, { recursive: true });

  const configPath = resolveKiloConfigPath(kiloConfigDir);

  // Read existing config or create empty object
  let config = {};
  if (fs.existsSync(configPath)) {
    try {
      const content = fs.readFileSync(configPath, 'utf8');
      config = parseJsonc(content);
    } catch (e) {
      // Cannot parse - DO NOT overwrite user's config
      const configFile = path.basename(configPath);
      console.log(`  ${yellow}⚠${reset} Could not parse ${configFile} - skipping permission config`);
      console.log(`    ${dim}Reason: ${e.message}${reset}`);
      console.log(`    ${dim}Your config was NOT modified. Fix the syntax manually if needed.${reset}`);
      return;
    }
  }

  // Ensure permission structure exists
  if (!config.permission || typeof config.permission !== 'object') {
    config.permission = {};
  }

  // Build the GSD path using the actual config directory
  // Use ~ shorthand if it's in the default location, otherwise use full path
  const defaultConfigDir = path.join(os.homedir(), '.config', 'kilo');
  const gsdPath = kiloConfigDir === defaultConfigDir
    ? '~/.config/kilo/gsd-core/*'
    : `${kiloConfigDir.replace(/\\/g, '/')}/gsd-core/*`;

  let modified = false;

  // Configure read permission
  if (!config.permission.read || typeof config.permission.read !== 'object') {
    config.permission.read = {};
  }
  if (config.permission.read[gsdPath] !== 'allow') {
    config.permission.read[gsdPath] = 'allow';
    modified = true;
  }

  // Configure external_directory permission (the safety guard for paths outside project)
  if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
    config.permission.external_directory = {};
  }
  if (config.permission.external_directory[gsdPath] !== 'allow') {
    config.permission.external_directory[gsdPath] = 'allow';
    modified = true;
  }

  if (!modified) {
    return; // Already configured
  }

  // Write config back
  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
  console.log(`  ${green}✓${reset} Configured read permission for GSD docs`);
}

/**
 * Verify a directory exists and contains files
 */
function verifyInstalled(dirPath, description) {
  if (!fs.existsSync(dirPath)) {
    console.error(`  ${yellow}✗${reset} Failed to install ${description}: directory not created`);
    return false;
  }
  try {
    const entries = fs.readdirSync(dirPath);
    if (entries.length === 0) {
      console.error(`  ${yellow}✗${reset} Failed to install ${description}: directory is empty`);
      return false;
    }
  } catch (e) {
    console.error(`  ${yellow}✗${reset} Failed to install ${description}: ${e.message}`);
    return false;
  }
  return true;
}

/**
 * Verify a file exists
 */
function verifyFileInstalled(filePath, description) {
  if (!fs.existsSync(filePath)) {
    console.error(`  ${yellow}✗${reset} Failed to install ${description}: file not created`);
    return false;
  }
  return true;
}

/**
 * Install to the specified directory for a specific runtime
 * @param {boolean} isGlobal - Whether to install globally or locally
 * @param {string} runtime - Target runtime ('claude', 'opencode', 'gemini', 'codex')
 */

// ──────────────────────────────────────────────────────
// Local Patch Persistence
// ──────────────────────────────────────────────────────

const PATCHES_DIR_NAME = 'gsd-local-patches';
const MANIFEST_NAME = 'gsd-file-manifest.json';

/**
 * Compute SHA256 hash of file contents
 */
function fileHash(filePath) {
  const content = fs.readFileSync(filePath);
  return crypto.createHash('sha256').update(content).digest('hex');
}

/**
 * Recursively collect all files in dir with their hashes
 */
function generateManifest(dir, baseDir) {
  if (!baseDir) baseDir = dir;
  const manifest = {};
  if (!fs.existsSync(dir)) return manifest;
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
    if (entry.isDirectory()) {
      Object.assign(manifest, generateManifest(fullPath, baseDir));
    } else {
      manifest[relPath] = fileHash(fullPath);
    }
  }
  return manifest;
}

function normalizeInstallRelativePath(relPath) {
  if (typeof relPath !== 'string' || relPath.trim() === '' || relPath.includes('\0')) {
    return null;
  }
  if (path.isAbsolute(relPath) || path.win32.isAbsolute(relPath)) {
    return null;
  }
  const normalized = relPath.replace(/\\/g, '/');
  const segments = normalized.split('/');
  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
    return null;
  }
  return segments.join('/');
}

function resolveInstallRelativePath(baseDir, relPath) {
  const normalized = normalizeInstallRelativePath(relPath);
  if (!normalized) return null;
  const root = path.resolve(baseDir);
  const fullPath = path.resolve(root, normalized);
  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
 */
function writeManifest(configDir, runtime = 'claude', options = {}) {
  const isOpencode = runtime === 'opencode';
  const isKilo = runtime === 'kilo';
  const isGemini = runtime === 'gemini';
  const isCodex = runtime === 'codex';
  const isCopilot = runtime === 'copilot';
  const isAntigravity = runtime === 'antigravity';
  const isCursor = runtime === 'cursor';
  const isWindsurf = runtime === 'windsurf';
  const isTrae = runtime === 'trae';
  const isCline = runtime === 'cline';
  const isKimi = runtime === 'kimi';
  const isHermes = runtime === 'hermes';
  const gsdDir = path.join(configDir, 'gsd-core');
  const commandsDir = path.join(configDir, 'commands', 'gsd');
  const opencodeCommandDir = path.join(configDir, 'command');
  // Hermes nests GSD skills under skills/gsd/ as a single category (#2841).
  // All other runtimes that use the Codex-style skills layout use a flat skills/ root.
  const codexSkillsDir = isHermes
    ? path.join(configDir, 'skills', 'gsd')
    : path.join(configDir, 'skills');
  const codexSkillsManifestPrefix = isHermes ? 'skills/gsd/' : 'skills/';
  const agentsDir = path.join(configDir, 'agents');
  const manifest = {
    version: pkg.version,
    timestamp: new Date().toISOString(),
    mode: options.mode === 'minimal' ? 'minimal' : 'full',
    files: {},
  };

  const gsdHashes = generateManifest(gsdDir);
  for (const [rel, hash] of Object.entries(gsdHashes)) {
    // Skip user-owned artifacts (e.g. USER-PROFILE.md). They are preserved
    // across reinstalls by preserveUserArtifacts and must NOT be hashed into
    // the manifest — otherwise saveLocalPatches() would flag every refresh
    // as a "local patch" (bug #2771). Single source of truth:
    // USER_OWNED_ARTIFACTS at top of file.
    if (USER_OWNED_ARTIFACTS.includes(rel)) continue;
    manifest.files['gsd-core/' + rel] = hash;
  }
  // Record commands/gsd/ for any runtime that emits it (Gemini globally,
  // Claude Code locally — see #2923). Manifest must reflect everything on
  // disk so saveLocalPatches() can detect user edits and so per-runtime
  // assertions about minimal-mode emit can read manifest.files instead of
  // re-walking the dir.
  if (fs.existsSync(commandsDir)) {
    const cmdHashes = generateManifest(commandsDir);
    for (const [rel, hash] of Object.entries(cmdHashes)) {
      manifest.files['commands/gsd/' + rel] = hash;
    }
  }
  if ((isOpencode || isKilo) && fs.existsSync(opencodeCommandDir)) {
    for (const file of fs.readdirSync(opencodeCommandDir)) {
      if (file.startsWith('gsd-') && file.endsWith('.md')) {
        manifest.files['command/' + file] = fileHash(path.join(opencodeCommandDir, file));
      }
    }
  }
  if ((isCodex || isCopilot || isAntigravity || isCursor || isWindsurf || isTrae || (!isOpencode && !isGemini)) && fs.existsSync(codexSkillsDir)) {
    // Hermes uses prefix '' (bare stem names); all others use 'gsd-'
    const skillListPrefix = isHermes ? '' : 'gsd-';
    for (const skillName of listCodexSkillNames(codexSkillsDir, skillListPrefix)) {
      const skillRoot = path.join(codexSkillsDir, skillName);
      const skillHashes = generateManifest(skillRoot);
      for (const [rel, hash] of Object.entries(skillHashes)) {
        manifest.files[`${codexSkillsManifestPrefix}${skillName}/${rel}`] = hash;
      }
    }
    // For Hermes, also hash the category DESCRIPTION.md so reinstall detects drift.
    if (isHermes) {
      const descPath = path.join(codexSkillsDir, 'DESCRIPTION.md');
      if (fs.existsSync(descPath)) {
        manifest.files['skills/gsd/DESCRIPTION.md'] = fileHash(descPath);
      }
    }
  }
  if (isKimi && fs.existsSync(agentsDir)) {
    const agentHashes = generateManifest(agentsDir);
    for (const [rel, hash] of Object.entries(agentHashes)) {
      const isRootAgent = rel === 'gsd.yaml' || rel === 'gsd.md';
      const isSubagent = /^subagents\/gsd-[^/]+\.(yaml|md)$/.test(rel);
      if (isRootAgent || isSubagent) {
        manifest.files['agents/' + rel] = hash;
      }
    }
  } else if (fs.existsSync(agentsDir)) {
    for (const file of fs.readdirSync(agentsDir)) {
      if (file.startsWith('gsd-') && (file.endsWith('.md') || file.endsWith('.toml'))) {
        manifest.files['agents/' + file] = fileHash(path.join(agentsDir, file));
      }
    }
  }
  // Track Cline directory-form artifacts in the manifest (issue #787): the
  // rules file and the PreToolUse hook. (~/.agents/AGENTS.md is tracked via its
  // marker block, not the per-configDir manifest, since it lives outside it.)
  if (isCline) {
    for (const rel of ['.clinerules/gsd.md', '.clinerules/hooks/PreToolUse']) {
      const dest = path.join(configDir, rel);
      if (fs.existsSync(dest)) {
        manifest.files[rel] = fileHash(dest);
      }
    }
  }

  // Track hook files so saveLocalPatches() can detect user modifications
  // Hooks are only installed for runtimes that use settings.json (not Codex/Copilot/Cline)
  if (!isCodex && !isCopilot && !isCline && !isKimi) {
    const hooksDir = path.join(configDir, 'hooks');
    if (fs.existsSync(hooksDir)) {
      for (const file of fs.readdirSync(hooksDir)) {
        if (file.startsWith('gsd-') && (file.endsWith('.js') || file.endsWith('.sh'))) {
          manifest.files['hooks/' + file] = fileHash(path.join(hooksDir, file));
        }
      }
      // Track hooks/lib/ helpers so saveLocalPatches() can back up user edits
      // to git-cmd.js (validate-commit classifier) and gsd-graphify-rebuild.sh.
      const hooksLibDir = path.join(hooksDir, 'lib');
      if (fs.existsSync(hooksLibDir)) {
        for (const file of fs.readdirSync(hooksLibDir)) {
          if (GSD_HOOK_LIB_FILES.includes(file)) {
            manifest.files['hooks/lib/' + file] = fileHash(path.join(hooksLibDir, file));
          }
        }
      }
    }
  }

  // Track scripts/changeset/ and scripts/lib/ so saveLocalPatches() can detect drift
  const changesetInstallDir = path.join(configDir, 'scripts', 'changeset');
  if (fs.existsSync(changesetInstallDir)) {
    for (const file of fs.readdirSync(changesetInstallDir)) {
      if (file.endsWith('.cjs')) {
        manifest.files['scripts/changeset/' + file] = fileHash(path.join(changesetInstallDir, file));
      }
    }
  }
  const scriptsLibInstallDir = path.join(configDir, 'scripts', 'lib');
  if (fs.existsSync(scriptsLibInstallDir)) {
    for (const file of fs.readdirSync(scriptsLibInstallDir)) {
      if (file.endsWith('.cjs')) {
        manifest.files['scripts/lib/' + file] = fileHash(path.join(scriptsLibInstallDir, file));
      }
    }
  }

  fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
  return manifest;
}

/**
 * Populate gsd-pristine/ with the transformed pristine versions of every
 * `modified` file, derived from the current package's source tree by
 * running the install transform pipeline (`copyWithPathReplacement`)
 * into a tmp directory, then copying out only the relevant paths.
 *
 * Pristine semantically represents "what the install would write to
 * configDir/<relPath> if the user had not modified it." This is what the
 * /gsd-reapply-patches Step 5 verifier (#2972) uses as the diff base
 * for "user-added lines" — lines in the user's backup that are NOT in
 * the pristine baseline. Without this dir, the verifier degrades to its
 * over-broad fallback ("every significant backup line"), exactly the
 * silent-success-on-lost-content failure mode #2969 was designed to
 * prevent (#2998).
 *
 * Implementation note: we run the FULL transform pipeline against a tmp
 * staging dir (one-time, only when modified.length > 0), then copy out
 * just the modified paths. This re-uses the existing transform code
 * exactly — pristine is byte-identical to what `copyWithPathReplacement`
 * would have written under normal install. Cost: one extra full transform
 * pass per install where local patches were detected; acceptable.
 */
function populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathPrefix, isGlobal }) {
  if (!modified || modified.length === 0) return 0;
  // Modified paths come from manifest.files which can live under several
  // install roots: gsd-core/, commands/gsd/, command/, skills/, agents/,
  // hooks/, plus runtime-specific root files (#3004 CR). Stage every
  // top-level dir that actually contains a modified path; root-level files
  // are copied directly without the transform pipeline (they don't need
  // path replacement).
  const stageRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-pristine-stage-'));
  let written = 0;
  try {
    const topLevels = new Set();
    const safeModified = [];
    for (const relPath of modified) {
      const norm = normalizeInstallRelativePath(relPath);
      if (!norm) continue;
      safeModified.push(norm);
      const slash = norm.indexOf('/');
      topLevels.add(slash === -1 ? '' : norm.slice(0, slash));
    }

    for (const top of topLevels) {
      if (top === '') {
        // Root-level files — copy directly from package source. The transform
        // pipeline is directory-oriented; root files don't need path-prefix
        // substitution (they're not markdown content with embedded paths).
        for (const relPath of safeModified) {
          const norm = normalizeInstallRelativePath(relPath);
          if (!norm) continue;
          if (norm.includes('/')) continue;
          const srcRef = resolveInstallRelativePath(packageSrc, norm);
          const stagedRef = resolveInstallRelativePath(stageRoot, norm);
          if (!srcRef || !stagedRef || !fs.existsSync(srcRef.fullPath)) continue;
          const stagedFile = stagedRef.fullPath;
          fs.mkdirSync(path.dirname(stagedFile), { recursive: true });
          fs.copyFileSync(srcRef.fullPath, stagedFile);
        }
        continue;
      }
      const srcDir = path.join(packageSrc, top);
      const stageDir = path.join(stageRoot, top);
      if (!fs.existsSync(srcDir)) continue;
      copyWithPathReplacement(srcDir, stageDir, pathPrefix, runtime, false, isGlobal);
    }

    for (const relPath of safeModified) {
      // Only populate pristine for paths we successfully staged. If a path's
      // source dir does not exist (obsolete manifest entry), skip silently
      // rather than corrupting pristine with stale data.
      const stagedRef = resolveInstallRelativePath(stageRoot, relPath);
      const outRef = resolveInstallRelativePath(pristineDir, relPath);
      if (!stagedRef || !outRef || !fs.existsSync(stagedRef.fullPath)) continue;
      fs.mkdirSync(path.dirname(outRef.fullPath), { recursive: true });
      fs.copyFileSync(stagedRef.fullPath, outRef.fullPath);
      written++;
    }
  } finally {
    try { fs.rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
  }
  return written;
}

/**
 * Detect user-modified GSD files by comparing against install manifest.
 * Backs up modified files to gsd-local-patches/ for reapply after update.
 * Also saves pristine copies (from manifest) to gsd-pristine/ to enable
 * three-way merge during reapply-patches (pristine vs user vs new).
 *
 * The optional `pristineCtx` parameter (set by the install entry point)
 * carries the source package root, runtime, pathPrefix, and isGlobal
 * needed to populate gsd-pristine/. If omitted (legacy callers), pristine
 * stays empty — the verifier falls back to its over-broad heuristic, same
 * behavior as before #2998.
 */
function saveLocalPatches(configDir, pristineCtx) {
  const manifestPath = path.join(configDir, MANIFEST_NAME);
  if (!fs.existsSync(manifestPath)) return [];

  let manifest;
  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { return []; }

  // Normalize legacy manifests written before #2771 fix: strip user-owned artifacts
  // that were incorrectly recorded so refreshes don't surface false patches warnings.
  if (manifest.files) {
    for (const artifact of USER_OWNED_ARTIFACTS) {
      delete manifest.files[`gsd-core/${artifact}`];
    }
  }

  const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
  const pristineDir = path.join(configDir, 'gsd-pristine');
  const modified = [];
  const pristineHashes = {};

  for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
    const safeRef = resolveInstallRelativePath(configDir, relPath);
    if (!safeRef) continue;
    const { relPath: safeRelPath, fullPath } = safeRef;
    if (!fs.existsSync(fullPath)) continue;
    const currentHash = fileHash(fullPath);
    if (currentHash !== originalHash) {
      // Back up the user's modified version
      const backupRef = resolveInstallRelativePath(patchesDir, safeRelPath);
      if (!backupRef) continue;
      const backupPath = backupRef.fullPath;
      fs.mkdirSync(path.dirname(backupPath), { recursive: true });
      fs.copyFileSync(fullPath, backupPath);
      modified.push(safeRelPath);
      pristineHashes[safeRelPath] = originalHash;
    }
  }

  // Save pristine copies of modified files from the CURRENT install (before wipe).
  // Pristine semantically represents "what the install would write to configDir
  // if the user had not modified it" — used by /gsd-reapply-patches Step 5
  // (#2972) as the diff baseline for the user-added-lines computation. Without
  // this dir the verifier degrades to its over-broad fallback heuristic (#2998).
  if (modified.length > 0) {
    const meta = {
      backed_up_at: new Date().toISOString(),
      from_version: manifest.version,
      from_manifest_timestamp: manifest.timestamp,
      files: modified,
      pristine_hashes: {}
    };
    // Record the original (pristine) hash for each modified file
    // This lets the reapply workflow verify reconstructed pristine files
    for (const relPath of modified) {
      meta.pristine_hashes[relPath] = pristineHashes[relPath];
    }
    fs.writeFileSync(path.join(patchesDir, 'backup-meta.json'), JSON.stringify(meta, null, 2));
    console.log('  ' + yellow + 'i' + reset + '  Found ' + modified.length + ' locally modified GSD file(s) — backed up to ' + PATCHES_DIR_NAME + '/');
    for (const f of modified) {
      console.log('     ' + dim + f + reset);
    }

    // #2998 / #3407: maintain gsd-pristine/ as the diff baseline for the
    // reapply-patches verifier (#2972).
    //
    // #3407 root-cause fix: the prior approach (#3004 CR) wiped gsd-pristine/
    // and re-populated it from pristineCtx.packageSrc (the NEW release source).
    // For files that changed between the old and new release this wrote NEW-
    // release bytes as the pristine baseline while backup-meta.json recorded
    // OLD-release hashes — a hash mismatch that caused the #3657 verifier guard
    // (OK_PRISTINE_DRIFT_DETECTED) to skip the baseline and fall back to over-
    // broad mode on every upgrade.
    //
    // Correct approach: `gsd-pristine/` is populated lazily by saveLocalPatches'
    // regenerate branch (not by a separate install-time step); the fix works by
    // induction across upgrades — each clean upgrade persists hash-validated
    // entries for the next run.  During this call we must PRESERVE entries whose
    // hash matches originalHash, not overwrite them with new-release bytes.
    //
    // Per-file decision:
    //   - sha256(gsd-pristine/X) === originalHash  →  correct; keep it
    //   - gsd-pristine/X exists but hash mismatch  →  stale from a previous
    //     buggy run (#3407); remove so verifier falls back cleanly
    //   - gsd-pristine/X absent                    →  attempt hash-validated
    //     regeneration: generate candidate from new-release source; if
    //     sha256(candidate) === originalHash the file is identical between
    //     old and new releases so candidate bytes ARE the old-release pristine
    //     and can be used; discard otherwise (over-broad fallback)
    if (pristineCtx) {
      let preserved = 0;
      // Track which relPaths had stale pristine entries (hash mismatch) that we
      // removed. After the regeneration pass we compute `removed` = stale entries
      // that could NOT be recovered (over-broad fallback applies to those only).
      const stalePaths = new Set();
      // Track which relPaths were successfully regenerated (from either missing or stale).
      const regeneratedPaths = new Set();
      const missingPaths = [];
      for (const relPath of modified) {
        const outRef = resolveInstallRelativePath(pristineDir, relPath);
        if (!outRef) continue;
        const { fullPath: pristinePath } = outRef;
        if (fs.existsSync(pristinePath)) {
          try {
            const onDiskHash = fileHash(pristinePath);
            if (onDiskHash === pristineHashes[relPath]) {
              preserved++;
              continue; // correct old-release bytes already in place — keep them
            }
          } catch { /* read error — treat as mismatch */ }
          // Hash mismatch or read error: stale pristine from a previous buggy
          // run (#3407). Remove so verifier falls back to over-broad mode.
          try { fs.rmSync(pristinePath, { force: true, recursive: true }); } catch { /* best-effort */ }
          // Only count as removed if the file is actually gone post-removal.
          if (!fs.existsSync(pristinePath)) {
            stalePaths.add(relPath);
          }
        }
        // File absent from gsd-pristine/ (or just removed above as stale):
        // attempt hash-validated regeneration from new-release source.
        missingPaths.push(relPath);
      }
      // Regenerate missing entries into a temp dir, then validate each hash
      // before promoting. Only files whose new-release generated bytes hash to
      // originalHash are safe to use — they were unchanged between releases.
      if (missingPaths.length > 0) {
        let tempPristineDir = null;
        try {
          tempPristineDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-pristine-regen-'));
          populatePristineDir({
            packageSrc: pristineCtx.packageSrc,
            pristineDir: tempPristineDir,
            modified: missingPaths,
            runtime: pristineCtx.runtime,
            pathPrefix: pristineCtx.pathPrefix,
            isGlobal: pristineCtx.isGlobal,
          });
          for (const relPath of missingPaths) {
            const tempRef = resolveInstallRelativePath(tempPristineDir, relPath);
            const outRef = resolveInstallRelativePath(pristineDir, relPath);
            if (!tempRef || !outRef || !fs.existsSync(tempRef.fullPath)) continue;
            try {
              const candidateHash = fileHash(tempRef.fullPath);
              if (candidateHash !== pristineHashes[relPath]) continue; // new-release differs — discard
              fs.mkdirSync(path.dirname(outRef.fullPath), { recursive: true });
              fs.copyFileSync(tempRef.fullPath, outRef.fullPath);
              regeneratedPaths.add(relPath);
            } catch { /* hash or copy error — skip; over-broad fallback applies */ }
          }
        } catch (err) {
          // Match the pre-fix behavior: log a warning and continue (verifier falls back to over-broad mode for missing files).
          console.warn(`gsd-pristine regen skipped: ${err.message}`);
        } finally {
          if (tempPristineDir) {
            try { fs.rmSync(tempPristineDir, { recursive: true, force: true }); } catch { /* best-effort */ }
          }
        }
      }
      // `regenerated` = total files successfully regenerated (from missing OR stale).
      const regenerated = regeneratedPaths.size;
      // `removed` = stale entries that were deleted and NOT subsequently regenerated.
      // Entries that were stale-deleted but then successfully regenerated are counted
      // only in `regenerated` — the counts are non-overlapping.
      const removed = [...stalePaths].filter(p => !regeneratedPaths.has(p)).length;
      if (preserved > 0) {
        console.log('  ' + green + '✓' + reset + '  Preserved ' + cyan + 'gsd-pristine/' + reset + ' (' + preserved + ' file(s)) for three-way merge');
      }
      if (regenerated > 0) {
        console.log('  ' + green + '✓' + reset + '  Regenerated ' + cyan + 'gsd-pristine/' + reset + ' (' + regenerated + ' file(s)) via hash-validated new-release source');
      }
      if (removed > 0) {
        console.log('  ' + yellow + 'i' + reset + '  Removed ' + removed + ' stale gsd-pristine/ snapshot(s); regenerated ' + regenerated + ' of those — falls back to over-broad verify heuristic for the rest');
      }
    }
  }
  return modified;
}

/**
 * After install, report backed-up patches for user to reapply.
 */
function reportLocalPatches(configDir, runtime = 'claude') {
  const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
  const metaPath = path.join(patchesDir, 'backup-meta.json');
  if (!fs.existsSync(metaPath)) return [];

  let meta;
  try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { return []; }

  if (meta.files && meta.files.length > 0) {
    const reapplyCommand = (runtime === 'opencode' || runtime === 'kilo' || runtime === 'copilot')
      ? '/gsd-update --reapply'
      : runtime === 'gemini'
        ? '/gsd:update --reapply'
        : runtime === 'codex'
          ? '$gsd-update --reapply'
        : runtime === 'cursor'
          ? 'gsd-update --reapply (mention the skill name)'
        : runtime === 'kimi'
          ? '/skill:gsd-update --reapply'
          : '/gsd-update --reapply';
    console.log('');
    console.log('  ' + yellow + 'Local patches detected' + reset + ' (from v' + meta.from_version + '):');
    for (const f of meta.files) {
      console.log('     ' + cyan + f + reset);
    }
    console.log('');
    console.log('  Your modifications are saved in ' + cyan + PATCHES_DIR_NAME + '/' + reset);
    console.log('  Run ' + cyan + reapplyCommand + reset + ' to merge them into the new version.');
    console.log('  Or manually compare and merge the files.');
    console.log('');
  }
  return meta.files || [];
}

function reportInstallerMigrationResult(result) {
  const summary = summarizeInstallerMigrationResult(result);
  if (!summary.hasReportableActions) return;

  console.log(`  ${green}✓${reset} Installer migrations`);
  for (const row of summary.rows) {
    const reason = row.reason ? ` — ${row.reason}` : '';
    console.log(`     ${row.label} ${dim}${row.relPath}${reset}${reason}`);
  }
}

function install(isGlobal, runtime = 'claude', options = {}) {
  const isOpencode = runtime === 'opencode';
  const isGemini = runtime === 'gemini';
  const isKilo = runtime === 'kilo';
  const isKimi = runtime === 'kimi';
  const isCodex = runtime === 'codex';
  const isCopilot = runtime === 'copilot';
  const isAntigravity = runtime === 'antigravity';
  const isCursor = runtime === 'cursor';
  const isWindsurf = runtime === 'windsurf';
  const isAugment = runtime === 'augment';
  const isTrae = runtime === 'trae';
  const isQwen = runtime === 'qwen';
  const isHermes = runtime === 'hermes';
  const isCodebuddy = runtime === 'codebuddy';
  const isCline = runtime === 'cline';
  const configIntent = resolveRuntimeConfigIntent(runtime);
  const dirName = getDirName(runtime);
  const src = path.join(__dirname, '..');

  if (isKimi && !isGlobal) {
    console.log(`  ${yellow}⚠${reset} Kimi local install is deferred for Phase 2.`);
    console.log(`      No .kimi-code/skills or .agents/skills project artifacts were written.`);
    console.log(`      Project-level Kimi install semantics remain deferred.`);
    return {
      runtime,
      skipped: true,
      reason: 'kimi_local_deferred',
      configDir: null,
      settingsPath: null,
      settings: null,
      statuslineCommand: null,
      updateBannerCommand: null,
      rollbackInstallerMigrations: () => {},
    };
  }

  // Reusable helper to copy hooks/lib/ (git-cmd.js + gsd-graphify-rebuild.sh).
  // Defined early so it is visible to both the main and Codex code paths.
  // `allowlist` (when non-empty) restricts copying to the named top-level entries,
  // keeping install scope aligned with GSD_HOOK_LIB_FILES (which uninstall/manifest manage).
  const copyLibDir = (sDir, dDir, allowlist = []) => {
    const allowed = allowlist.length > 0 ? new Set(allowlist) : null;
    for (const entry of fs.readdirSync(sDir)) {
      if (allowed && !allowed.has(entry)) continue;
      const s = path.join(sDir, entry);
      const d = path.join(dDir, entry);
      let st;
      try { st = fs.lstatSync(s); } catch (_) { continue; }
      if (st.isSymbolicLink()) continue; // defense-in-depth
      if (st.isDirectory()) {
        fs.mkdirSync(d, { recursive: true });
        copyLibDir(s, d);
      } else if (entry.endsWith('.sh')) {
        let content = fs.readFileSync(s, 'utf8');
        content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
        fs.writeFileSync(d, content);
        try { fs.chmodSync(d, 0o755); } catch (_) { /* Windows */ }
      } else {
        fs.copyFileSync(s, d);
        if (entry.endsWith('.js')) {
          try { fs.chmodSync(d, 0o755); } catch (_) { /* Windows */ }
        }
      }
    }
  };

  // Get the target directory based on runtime and install type.
  // Cline local installs write to the project root (like Claude Code) — .clinerules
  // lives at the root, not inside a .cline/ subdirectory.
  const targetDir = isGlobal
    ? getGlobalConfigDir(runtime, explicitConfigDir)
    : isCline
      ? process.cwd()
      : path.join(process.cwd(), dirName);

  const locationLabel = isGlobal
    ? targetDir.replace(os.homedir(), '~')
    : targetDir.replace(process.cwd(), '.');

  // Path prefix for file references in markdown content (e.g. gsd-tools.cjs).
  // Replaces $HOME/.claude/ or ~/.claude/ so the result is <pathPrefix>gsd-core/bin/...
  // For global installs: use $HOME/ so paths expand correctly inside double-quoted
  // shell commands (~ does NOT expand inside double quotes, causing MODULE_NOT_FOUND).
  // For local installs: use resolved absolute path (may be outside $HOME).
  // Exception: OpenCode does not expand $HOME in @file references on any platform —
  // `@$HOME/...` is treated as a literal path relative to the config dir, producing
  // `command/$HOME/...` (file not found). Use the absolute path for OpenCode so
  // @-references resolve correctly (#2376 Windows, #2831 macOS/Linux).
  // gsd update marker re-application (ADR-0010 Deviation 2):
  // Resolve which profile to use for this runtime's install:
  //   1. --minimal / --core-only → back-compat alias for the core profile
  //   2. Explicit --profile=<name> → use it (overrides any marker)
  //   3. Marker exists in targetDir → honor it (prevents silent expansion on update)
  //   4. Else → 'full' (back-compat for fresh non-interactive installs)
  //
  // Multi-runtime disagreement: if installing across runtimes and their markers
  // differ, the caller may use mostRestrictiveProfile() across the per-runtime
  // results — here we resolve each runtime independently.
  //
  // ADR-857 phase 4c: ALL profiles (including core/minimal) use stageSkillsForProfile
  // with the registry-aware _resolvedProfile so future tier:core capabilities are
  // staged on core installs.  The 'minimal' back-compat distinction is now ONLY the
  // empty manifest (core profile has no transitive deps); the registry IS consulted.
  // MINIMAL is intentionally the same skill set as the 'core' profile
  // (MINIMAL_ALLOWLIST_SET === Set(PROFILES.core)) — it is NOT a separately curated
  // subset.  Any future tier:core capability therefore DOES belong in a minimal/core
  // install.  Using stageSkillsForProfile(_resolvedProfile) honors the registry while
  // keeping the effective skill set identical to the prior stageSkillsForMode path
  // until a tier:core capability is registered.
  const _activeProfileName = hasMinimal
    ? 'core'  // --minimal is a back-compat alias for the core profile; marker records 'core'
    : resolveEffectiveProfile({
        requestedProfileName: _requestedProfileName,
        targetDir,
      });
  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.  Registry IS
  // consulted so tier:core capability skills are included when registered.
  const _commandsDir = path.join(src, 'commands', 'gsd');
  const _skillsManifest = _isCoreProfileAlias ? new Map() : loadSkillsManifest(_commandsDir);
  const _resolvedProfile = resolveProfile({
    modes: [_activeProfileName],
    manifest: _skillsManifest,
    registry: _capabilityRegistry,
  });
  // Unified staging function: all profiles use stageSkillsForProfile with the
  // registry-aware _resolvedProfile (ADR-857 phase 4c cutover).
  function _stageSkills(commandsGsdDir) {
    return stageSkillsForProfile(commandsGsdDir, _resolvedProfile);
  }
  function _stageAgents(agentsDir) {
    if (_isCoreProfileAlias) return agentsDir;
    return stageAgentsForProfile(agentsDir, _resolvedProfile);
  }
  const persistActiveProfileMarker = () => {
    try {
      writeActiveProfile(targetDir, _activeProfileName);
    } catch {
      // Non-fatal: marker persistence failure doesn't break the install.
    }
  };

  const resolvedTarget = path.resolve(targetDir).replace(/\\/g, '/');
  const homeDir = os.homedir().replace(/\\/g, '/');
  const isWindowsHost = process.platform === 'win32';
  const pathPrefix = computePathPrefix({
    isGlobal,
    isOpencode,
    isWindowsHost,
    resolvedTarget,
    homeDir,
  });

  let runtimeLabel = 'Claude Code';
  if (isOpencode) runtimeLabel = 'OpenCode';
  if (isGemini) runtimeLabel = 'Gemini';
  if (isKilo) runtimeLabel = 'Kilo';
  if (isCodex) runtimeLabel = 'Codex';
  if (isCopilot) runtimeLabel = 'Copilot';
  if (isAntigravity) runtimeLabel = 'Antigravity';
  if (isCursor) runtimeLabel = 'Cursor';
  if (isWindsurf) runtimeLabel = 'Windsurf';
  if (isAugment) runtimeLabel = 'Augment';
  if (isTrae) runtimeLabel = 'Trae';
  if (isQwen) runtimeLabel = 'Qwen Code';
  if (isHermes) runtimeLabel = 'Hermes Agent';
  if (isKimi) runtimeLabel = 'Kimi';
  if (isCodebuddy) runtimeLabel = 'CodeBuddy';
  if (isCline) runtimeLabel = 'Cline';

  console.log(`  Installing for ${cyan}${runtimeLabel}${reset} to ${cyan}${locationLabel}${reset}\n`);

  // 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
  // the install transform pipeline, giving the reapply-patches Step 5
  // verifier a real diff baseline (#2998).
  saveLocalPatches(targetDir, {
    packageSrc: src,
    runtime,
    pathPrefix,
    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
  // entire install atomically — not just config.toml.
  //
  // Captured BEFORE the first Codex-specific write (skills/) so the snapshots
  // reflect the true pre-GSD state. Non-Codex runtimes skip this block.
  //
  // Snapshot contents:
  //   codexPreInstallSkillNames  — Set of gsd-* skill dir names that existed
  //   codexPreInstallSkillContents — Map<skillName, Map<relPath, Buffer>> of
  //       the full file tree of each pre-existing gsd-* skill dir, so that
  //       overwritten dirs can be fully restored on rollback (not just removed).
  //   codexPreInstallAgentFiles  — Set of gsd-*.{md,toml} filenames in agents/
  //   codexPreInstallAgentContents — Map<filename, Buffer> of pre-existing agent
  //       file bytes, enabling full content restore (not just deletion) on rollback.
  //   codexPreInstallVersionBytes — Buffer (or null) of gsd-core/VERSION
  //
  // These are referenced by restoreCodexSnapshot(), defined below inside the
  // config block. Defining the variables here (outer scope) makes them
  // accessible by closure.
  const codexPreInstallSkillNames = new Set();
  // Map<skillDirName, Map<relPath, Buffer>> — full content snapshot of each
  // pre-existing gsd-* skill directory. Best-effort: read errors are silently
  // skipped so a partial snapshot is still better than none.
  const codexPreInstallSkillContents = new Map();
  const codexPreInstallAgentFiles = new Set();
  // Map<filename, Buffer> — content snapshot of each pre-existing gsd-* agent file.
  const codexPreInstallAgentContents = new Map();
  let codexPreInstallVersionBytes = null;
  if (isCodex && !isMinimalMode(_effectiveInstallMode)) {
    const _preSkillsDir = path.join(targetDir, 'skills');
    if (fs.existsSync(_preSkillsDir)) {
      for (const entry of fs.readdirSync(_preSkillsDir, { withFileTypes: true })) {
        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
          codexPreInstallSkillNames.add(entry.name);
          // Recursively snapshot all files in this skill dir.
          const skillDir = path.join(_preSkillsDir, entry.name);
          const fileMap = new Map();
          const _snapshotDir = (dir, relBase) => {
            let children;
            try { children = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
            for (const child of children) {
              const relPath = relBase ? `${relBase}/${child.name}` : child.name;
              const fullPath = path.join(dir, child.name);
              if (child.isDirectory()) {
                _snapshotDir(fullPath, relPath);
              } else {
                try { fileMap.set(relPath, fs.readFileSync(fullPath)); } catch (_) { /* best-effort */ }
              }
            }
          };
          _snapshotDir(skillDir, '');
          codexPreInstallSkillContents.set(entry.name, fileMap);
        }
      }
    }
    const _preAgentsDir = path.join(targetDir, 'agents');
    if (fs.existsSync(_preAgentsDir)) {
      for (const file of fs.readdirSync(_preAgentsDir)) {
        if (file.startsWith('gsd-') && (file.endsWith('.md') || file.endsWith('.toml'))) {
          codexPreInstallAgentFiles.add(file);
          try {
            codexPreInstallAgentContents.set(file, fs.readFileSync(path.join(_preAgentsDir, file)));
          } catch (_) { /* best-effort */ }
        }
      }
    }
    const _preVersionPath = path.join(targetDir, 'gsd-core', 'VERSION');
    if (fs.existsSync(_preVersionPath)) {
      try { codexPreInstallVersionBytes = fs.readFileSync(_preVersionPath); } catch (_) { /* best-effort */ }
    }
  }

  // #3245 CR finding 2 — Rollback coverage extends to ALL post-snapshot operations,
  // not just the Codex config/hook error paths. Any throw between snapshot capture and
  // the Codex config block (skills copy, agents copy, VERSION write, manifest write, etc.)
  // must also trigger rollback so the caller is never left in a partially-installed state.
  //
  // _codexPreConfigRollback covers the four surfaces that can be mutated before
  // config.toml is touched: skills/, agents/, gsd-core/VERSION, and orphaned
  // atomic-write temp files. It is safe to call before any writes have happened.
  // The full restoreCodexSnapshot() (defined inside the config block) additionally
  // handles config.toml, which is not yet touched at this point in the pipeline.
  const _codexPreConfigRollback = !isCodex || isMinimalMode(_effectiveInstallMode) ? null : () => {
    rollbackInstallerMigrations();
    // skills/gsd-* — pass 1: restore snapshot entries (may be absent if deleted mid-install).
    const _earlySkillsDir = path.join(targetDir, 'skills');
    for (const skillName of codexPreInstallSkillNames) {
      const skillDirPath = path.join(_earlySkillsDir, skillName);
      const fileMap = codexPreInstallSkillContents.get(skillName);
      try {
        fs.rmSync(skillDirPath, { recursive: true, force: true });
        fs.mkdirSync(skillDirPath, { recursive: true });
        if (fileMap) {
          for (const [relPath, buf] of fileMap) {
            const destFile = path.join(skillDirPath, relPath);
            try {
              fs.mkdirSync(path.dirname(destFile), { recursive: true });
              fs.writeFileSync(destFile, buf);
            } catch (_) { /* best-effort */ }
          }
        }
      } catch (_) { /* best-effort */ }
    }
    // skills/gsd-* — pass 2: remove any newly-created dirs not in the snapshot.
    if (fs.existsSync(_earlySkillsDir)) {
      try {
        for (const entry of fs.readdirSync(_earlySkillsDir, { withFileTypes: true })) {
          if (entry.isDirectory() && entry.name.startsWith('gsd-') && !codexPreInstallSkillNames.has(entry.name)) {
            try { fs.rmSync(path.join(_earlySkillsDir, entry.name), { recursive: true, force: true }); }
            catch (_) { /* best-effort */ }
          }
        }
      } catch (_) { /* best-effort */ }
    }
    // agents/gsd-* — pass 1: restore snapshot entries.
    const _earlyAgentsDir = path.join(targetDir, 'agents');
    for (const file of codexPreInstallAgentFiles) {
      const buf = codexPreInstallAgentContents.get(file);
      if (buf !== undefined) {
        try {
          fs.mkdirSync(_earlyAgentsDir, { recursive: true });
          fs.writeFileSync(path.join(_earlyAgentsDir, file), buf);
        } catch (_) { /* best-effort */ }
      }
    }
    // agents/gsd-* — pass 2: remove any newly-created files not in the snapshot.
    if (fs.existsSync(_earlyAgentsDir)) {
      try {
        for (const file of fs.readdirSync(_earlyAgentsDir)) {
          if (file.startsWith('gsd-') && (file.endsWith('.md') || file.endsWith('.toml')) && !codexPreInstallAgentFiles.has(file)) {
            try { fs.unlinkSync(path.join(_earlyAgentsDir, file)); } catch (_) { /* best-effort */ }
          }
        }
      } catch (_) { /* best-effort */ }
    }
    // gsd-core/VERSION
    const _earlyVersionPath = path.join(targetDir, 'gsd-core', 'VERSION');
    if (codexPreInstallVersionBytes !== null) {
      try { fs.writeFileSync(_earlyVersionPath, codexPreInstallVersionBytes); } catch (_) { /* best-effort */ }
    } else if (fs.existsSync(_earlyVersionPath)) {
      try { fs.unlinkSync(_earlyVersionPath); } catch (_) { /* best-effort */ }
    }
    // Orphaned atomic-write temp files.
    const _earlyTmpPattern = /\.tmp-\d+-\d+$/;
    function _earlyCleanTmpFiles(dir) {
      if (!fs.existsSync(dir)) return;
      let entries;
      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
      for (const entry of entries) {
        const full = path.join(dir, entry.name);
        if (entry.isDirectory()) {
          _earlyCleanTmpFiles(full);
        } else if (_earlyTmpPattern.test(entry.name) && __atomicWrittenTmps.has(full)) {
          try { fs.unlinkSync(full); } catch (_) { /* best-effort */ }
        }
      }
    }
    _earlyCleanTmpFiles(targetDir);
  };

  // Run manifest-backed cleanup migrations after rollback snapshots exist and
  // before package materialization. Codex rollback paths invoke the migration
  // rollback handle if a later install step fails.
  //
  // Runtime scope comes from docs/installer-migrations.md#runtime-configuration-contract-registry:
  // every supported runtime uses this same planner/apply/report path, while
  // individual migration records decide whether a runtime-specific config
  // rewrite is allowed by that runtime's documented ownership boundary.
  // #3245 CR finding 2 — wrap the pre-config install operations in a try/catch so
  // that ANY throw between snapshot capture and the Codex config block triggers rollback.
  // Non-Codex paths are unaffected (_codexPreConfigRollback is null for them).
  //
  // agentsSrc is declared here (let, not const) because installCodexConfig() inside the
  // Codex config block below also references it, and that block is outside the try scope.
  let agentsSrc = path.join(src, 'agents');
  // Capture upgrade signal BEFORE files are written (#683). Must be declared at function
  // 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'));
  try {
  installerMigrationResult = runInstallerMigrations({
    configDir: targetDir,
    runtime,
    scope: isGlobal ? 'global' : 'local',
    migrations: options.installerMigrations,
    baselineScan: true,
  });
  // #3541: non-interactive runs (typical /gsd-update via Claude Code) have
  // no stdin TTY and therefore no way to answer prompt-user migration
  // actions. Resolve safe categories by classification (stale SDK build
  // artifacts → remove; user-facing skills → keep; bundled GSD hooks →
  // remove [#3610]) and log every resolution; anything that cannot be
  // safely defaulted falls through to assertInstallerMigrationsUnblocked,
  // which now emits a grouped error with the documented resolution path.
  //
  // #3610: the classifier-based resolution must run regardless of TTY.
  // For unambiguous categories (e.g. `hooks/gsd-*` bundled hooks left
  // behind by a previous version), there is no actual "user choice" to
  // make — the file is a known GSD-managed artifact and the installer is
  // about to write the fresh bundled version. Gating the resolver on
  // `!isTTY` made `npx @opengsd/gsd-core@latest --codex` hard-abort with
  // 12 blocked bundled hooks. The env-override branch (operator-supplied
  // GSD_INSTALLER_MIGRATION_RESOLVE) still applies only in non-TTY mode.
  const _migrationIsTty = process.stdin && process.stdin.isTTY === true;
  if (Array.isArray(installerMigrationResult.blocked) &&
      installerMigrationResult.blocked.length > 0 &&
      installerMigrationResult.plan &&
      Array.isArray(installerMigrationResult.plan.actions)) {
    const { resolutions } = resolveInstallerMigrationPromptsForNonTty(
      installerMigrationResult,
      { isTty: false }
    );
    for (const entry of resolutions) {
      console.log(
        `  ↪ installer-migration auto-resolved: ${entry.relPath} → ${entry.choice} ` +
        `(category=${entry.category}, source=${entry.source})`
      );
    }
    // If we resolved anything, the original run returned early without
    // applying the (now-unblocked) plan — apply it here.
    if (resolutions.length > 0 && installerMigrationResult.plan.blocked.length === 0) {
      const applyResult = applyInstallerMigrationPlan({
        configDir: targetDir,
        plan: installerMigrationResult.plan,
      });
      installerMigrationResult = {
        ...installerMigrationResult,
        ...applyResult,
        blocked: [],
      };
    }
  }
  reportInstallerMigrationResult(installerMigrationResult);
  assertInstallerMigrationsUnblocked(installerMigrationResult);

  // Artifact install dispatcher — routes to layout-driven path for all
  // skills-based runtimes (both full and minimal/core profiles); keeps
  // back-compat paths for commands-based runtimes (OpenCode/Kilo/Gemini/
  // Claude-local).
  //
  // installRuntimeArtifacts handles legacy migration + skill/agent staging
  // via layout kinds for all profile modes. _resolvedProfile already reflects
  // the user's --profile=core / --minimal choice.
  //
  // Non-layout side-effects preserved inline:
  //   Hermes: writeHermesCategoryDescription (not a layout kind)
  //   Cline global: skills emitted via layout; .clinerules still written below (#782)
  //   Cline local: no skills (only .clinerules) — falls through to cline-rules surface
  //   Gemini: conflict-detection logic (not expressible in layout)
  //   OpenCode/Kilo: copyFlattenedCommands (frontmatter conversion not in commandsKind)
  //   Claude local: copyWithPathReplacement + stale-skills cleanup

  // Layout-driven path for all skills-based runtimes (full and minimal modes).
  // applyRuntimeContentRewritesInPlace (called inside installRuntimeArtifacts)
  // handles per-runtime path + branding rewrites, including Qwen/Hermes.
  // Cline global: emit skills to ~/.cline/skills/ (Cline >= v3.48.0 — #782).
  const _isSkillsRuntime = isCodex || isCopilot || isAntigravity || isCursor || isWindsurf ||
    isAugment || isTrae || isCodebuddy || isQwen || isHermes ||
    isKimi ||
    (runtime === 'claude' && isGlobal) ||
    (isCline && isGlobal);

  if (_isSkillsRuntime) {
    // Layout-driven install for skills-based runtimes (full and minimal modes)
    const scope = isGlobal ? 'global' : 'local';
    installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile);

    // #774 — Codex only: write agents/openai.yaml TUI chip metadata alongside each
    // installed skill so the /skills popup shows name + description for each gsd-* skill.
    // The SkillMetadataFile is loaded by codex-rs/core-skills/src/loader.rs from
    // <skill-dir>/agents/openai.yaml; absence is silently tolerated (fails open).
    // We parse the SKILL.md frontmatter to extract short-description already emitted
    // by convertClaudeCommandToCodexSkill and use it as the TUI chip description.
    if (isCodex) {
      writeCodexSkillMetadataFiles(path.join(targetDir, 'skills'));
    }

    // Hermes only: write DESCRIPTION.md for the gsd/ category after layout install
    if (isHermes) {
      writeHermesCategoryDescription(path.join(targetDir, 'skills', 'gsd'));
    }

    // Verify installed artifacts and report
    if (isHermes) {
      const hermesSkillsDir = path.join(targetDir, 'skills', 'gsd');
      if (fs.existsSync(hermesSkillsDir)) {
        // Hermes layout uses prefix: '' — skill dirs have bare stem names (no gsd- prefix)
        const count = fs.readdirSync(hermesSkillsDir, { withFileTypes: true })
          .filter(e => e.isDirectory()).length;
        if (count > 0) {
          console.log(`  ${green}✓${reset} Installed ${count} skills to skills/gsd/`);
        } else {
          failures.push('skills/gsd/*');
        }
      } else {
        failures.push('skills/gsd/*');
      }
    } else if (isKimi) {
      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;
        if (count > 0) {
          console.log(`  ${green}✓${reset} Installed ${count} Kimi skills to skills/`);
        } else {
          failures.push('skills/gsd-*');
        }
      } else {
        failures.push('skills/gsd-*');
      }
      if (fs.existsSync(rootAgentPath)) {
        console.log(`  ${green}✓${reset} Generated Kimi root agent: ${rootAgentPath}`);
        console.log(`      Launch with: kimi --agent-file ${rootAgentPath}`);
      } else {
        failures.push('agents/gsd.yaml');
      }
    } else {
      const skillsDir = path.join(targetDir, 'skills');
      if (fs.existsSync(skillsDir)) {
        const count = fs.readdirSync(skillsDir, { withFileTypes: true })
          .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
        if (count > 0) {
          console.log(`  ${green}✓${reset} Installed ${count} skills to skills/`);
        } else {
          failures.push('skills/gsd-*');
        }
      } else {
        failures.push('skills/gsd-*');
      }
      // Augment: also verify commands/ (emitted alongside skills/)
      if (isAugment) {
        const commandsDir = path.join(targetDir, 'commands');
        if (fs.existsSync(commandsDir)) {
          const cmdCount = fs.readdirSync(commandsDir)
            .filter(f => f.startsWith('gsd-') && f.endsWith('.md')).length;
          if (cmdCount > 0) {
            console.log(`  ${green}✓${reset} Installed ${cmdCount} commands to commands/`);
          } else {
            failures.push('commands/gsd-*');
          }
        } else {
          failures.push('commands/gsd-*');
        }
      }

      // Cursor only: also report the commands/ output (#785 — Cursor 1.6 slash commands)
      if (isCursor) {
        const commandsDir = path.join(targetDir, 'commands');
        if (fs.existsSync(commandsDir)) {
          const cmdCount = fs.readdirSync(commandsDir)
            .filter(f => f.startsWith('gsd-') && f.endsWith('.md')).length;
          if (cmdCount > 0) {
            console.log(`  ${green}✓${reset} Installed ${cmdCount} slash commands to commands/`);
          } else {
            failures.push('commands/gsd-*');
          }
        } else {
          failures.push('commands/gsd-*');
        }
      }

      // CodeBuddy only: also report the commands/ output (#789 — slash commands)
      if (isCodebuddy) {
        const commandsDir = path.join(targetDir, 'commands');
        if (fs.existsSync(commandsDir)) {
          const cmdCount = fs.readdirSync(commandsDir)
            .filter(f => f.startsWith('gsd-') && f.endsWith('.md')).length;
          if (cmdCount > 0) {
            console.log(`  ${green}✓${reset} Installed ${cmdCount} slash commands to commands/`);
          } else {
            failures.push('commands/gsd-*');
          }
        } else {
          failures.push('commands/gsd-*');
        }
      }
    }
  } else if (isOpencode || isKilo) {
    // OpenCode/Kilo: flat structure in command/ directory
    const commandDir = path.join(targetDir, 'command');
    fs.mkdirSync(commandDir, { recursive: true });

    // Copy commands/gsd/*.md as command/gsd-*.md (flatten structure)
    const gsdSrc = _stageSkills(_commandsDir);
    copyFlattenedCommands(gsdSrc, commandDir, 'gsd', pathPrefix, runtime);
    if (verifyInstalled(commandDir, 'command/gsd-*')) {
      const count = fs.readdirSync(commandDir).filter(f => f.startsWith('gsd-')).length;
      console.log(`  ${green}✓${reset} Installed ${count} commands to command/`);
    } else {
      failures.push('command/gsd-*');
    }

    // Also emit OpenCode-family skills (skills/<name>/SKILL.md). OpenCode and
    // Kilo support native, on-demand skills in addition to flat commands — see
    // resolveRuntimeArtifactLayout's opencode/kilo entries. Derive skills from
    // the SAME staged command set (gsdSrc) so both surfaces match exactly. (#784)
    const _skillCount = installOpencodeFamilySkills(runtime, targetDir, gsdSrc, pathPrefix);
    if (_skillCount > 0) {
      console.log(`  ${green}✓${reset} Installed ${_skillCount} skills to skills/`);
    } else {
      failures.push('skills/gsd-*');
    }
  } else if (isCline) {
    // Cline local install: rules-based only — commands are embedded in .clinerules (generated below).
    // No skills/commands directory needed for local installs.
    // Global installs are handled above by _isSkillsRuntime (#782).
    console.log(`  ${green}✓${reset} Cline: commands will be available via .clinerules`);
  } else if (isGemini) {
    // #3037: when running --local --gemini and a GSD-managed user-scope
    // command directory already exists at ~/.gemini/commands/gsd/, skip
    // the local copy. Gemini conflict-detects by command name across
    // scopes and renames every overlapping /gsd:* command to
    // /workspace.gsd:* and /user.gsd:*, breaking the documented namespace.
    // The user-scope install already provides the same commands, so the
    // local copy adds zero value at the cost of namespace conflicts.
    //
    // CR #3041 (Major): the detection must be specific to PACKAGE-MANAGED
    // GSD content, not just "directory is non-empty". A user who hand-
    // dropped a single override (e.g. ~/.gemini/commands/gsd/my-override
    // .toml) would otherwise be unable to run a local install at all.
    // Detection rule: at least 3 of the canonical GSD command files
    // ('help.toml', 'progress.toml', 'new-project.toml') must be present.
    // These three ship in every GSD Gemini install (minimal mode included
    // — they're in the core skill set per #2790's consolidation), and 3-of-
    // 3 with that specific basename set is structurally impossible to
    // produce by accident.
    const homeGeminiGsd = path.join(os.homedir(), '.gemini', 'commands', 'gsd');
    const GSD_MANAGED_CANARIES = ['help.toml', 'progress.toml', 'new-project.toml'];
    const userScopeHasGsd =
      !isGlobal &&
      path.resolve(targetDir) !== path.resolve(path.join(os.homedir(), '.gemini')) &&
      fs.existsSync(homeGeminiGsd) &&
      GSD_MANAGED_CANARIES.every((f) =>
        fs.existsSync(path.join(homeGeminiGsd, f))
      );

    if (userScopeHasGsd) {
      console.log(
        `  ${yellow}⚠${reset}  Skipping commands/gsd/ for local install — GSD is already installed at user scope (${homeGeminiGsd}).`
      );
      console.log(
        `      Gemini conflict-detects across scopes and would rename every /gsd:* command to /workspace.gsd:* and /user.gsd:*.`
      );
      console.log(
        `      The user-scope install already provides /gsd:* commands in this project; no local copy is needed.`
      );
    } else {
      const commandsDir = path.join(targetDir, 'commands');
      fs.mkdirSync(commandsDir, { recursive: true });
      const gsdSrc = _stageSkills(_commandsDir);
      const gsdDest = path.join(commandsDir, 'gsd');
      copyWithPathReplacement(gsdSrc, gsdDest, pathPrefix, runtime, true, isGlobal);
      if (verifyInstalled(gsdDest, 'commands/gsd')) {
        console.log(`  ${green}✓${reset} Installed commands/gsd`);
      } else {
        failures.push('commands/gsd');
      }
    }
  } else {
    // Claude Code local: commands/gsd/ format — Claude Code reads local project
    // commands from .claude/commands/gsd/, not .claude/skills/
    const commandsDir = path.join(targetDir, 'commands');
    fs.mkdirSync(commandsDir, { recursive: true });
    const gsdSrc = _stageSkills(_commandsDir);
    const gsdDest = path.join(commandsDir, 'gsd');
    copyWithPathReplacement(gsdSrc, gsdDest, pathPrefix, runtime, true, isGlobal);
    if (verifyInstalled(gsdDest, 'commands/gsd')) {
      const count = fs.readdirSync(gsdDest).filter(f => f.endsWith('.md')).length;
      console.log(`  ${green}✓${reset} Installed ${count} commands to commands/gsd/`);
    } else {
      failures.push('commands/gsd');
    }

    // Clean up any stale skills/ from a previous local install
    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-'));
      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/`);
      }
    }
  }

  // Copy gsd-core skill with path replacement
  // Preserve user-generated files before the wipe-and-copy so they survive re-install
  const skillSrc = path.join(src, 'gsd-core');
  const skillDest = path.join(targetDir, 'gsd-core');
  const savedGsdArtifacts = preserveUserArtifacts(skillDest, USER_OWNED_ARTIFACTS);
  copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal);
  restoreUserArtifacts(skillDest, savedGsdArtifacts);
  if (verifyInstalled(skillDest, 'gsd-core')) {
    console.log(`  ${green}✓${reset} Installed workflow assets`);
  } else {
    failures.push('gsd-core');
  }

  // Copy shared manifests into the gsd-core payload
  // at the co-located path that CJS modules resolve first:
  //   gsd-core/bin/shared/*.json
  //
  // This source now lives under gsd-core/bin/shared in-repo.
  const sharedPayloadFiles = [
    'model-catalog.json',
    'config-defaults.manifest.json',
    'config-schema.manifest.json',
    'runtime-aliases.manifest.json',
  ];
  for (const fileName of sharedPayloadFiles) {
    const sharedSrc = path.join(src, 'gsd-core', 'bin', 'shared', fileName);
    const sharedDest = path.join(skillDest, 'bin', 'shared', fileName);
    const displayPath = `gsd-core/bin/shared/${fileName}`;
    if (fs.existsSync(sharedSrc)) {
      fs.mkdirSync(path.dirname(sharedDest), { recursive: true });
      fs.copyFileSync(sharedSrc, sharedDest);
      if (verifyFileInstalled(sharedDest, displayPath)) {
        console.log(`  ${green}✓${reset} Installed ${displayPath}`);
      } else {
        failures.push(displayPath);
      }
    } else {
      failures.push(`gsd-core/bin/shared/${fileName} (source missing)`);
    }
  }

  // Copy agents to agents directory.
  // Skipped under --minimal: gsd-* subagent descriptions are eagerly loaded
  // into the runtime's Agent tool schema, costing ~6k tokens per turn even
  // when no GSD workflow is active. See open-gsd/gsd-core#2762.
  // Note: agentsSrc is declared as let before the enclosing try block so it
  // is accessible by installCodexConfig() in the Codex config section below.
  agentsSrc = _stageAgents(path.join(src, 'agents'));
  const agentsDest = path.join(targetDir, 'agents');

  // Always remove stale gsd-* agents first so re-installing with
  // `--minimal` actually shrinks a previously-full install.
  // For Codex this also covers per-agent `.toml` files alongside the `.md`
  // sources so a full → minimal switch doesn't leave stale registrations.
  if (fs.existsSync(agentsDest)) {
    for (const file of fs.readdirSync(agentsDest)) {
      if (
        file.startsWith('gsd-') &&
        (file.endsWith('.md') || (isCodex && file.endsWith('.toml')))
      ) {
        fs.unlinkSync(path.join(agentsDest, file));
      }
    }
  }

  if (isKimi) {
    console.log(`  ${dim}↳${reset} Kimi custom agent YAML/prompt artifacts were installed via runtime artifact layout`);
  } else if (isMinimalMode(_effectiveInstallMode)) {
    // Codex registers agents in `config.toml` via `[agents.gsd-*]` sections.
    // Without stripping them here, a full → minimal reinstall would leave the
    // runtime advertising the old full agent surface even though the agent
    // files are gone. Reuse the same helper that powers `--uninstall`.
    if (isCodex) {
      const codexConfigPath = path.join(targetDir, 'config.toml');
      if (fs.existsSync(codexConfigPath)) {
        const existing = fs.readFileSync(codexConfigPath, 'utf8');
        const cleaned = stripGsdFromCodexConfig(existing);
        if (cleaned === null) {
          fs.unlinkSync(codexConfigPath);
        } else if (cleaned !== existing) {
          fs.writeFileSync(codexConfigPath, cleaned);
        }
      }
    }
    console.log(`  ${dim}↳${reset} Skipping agents (minimal install — run \`gsd update\` without \`--minimal\` to add full surface)`);
  } else if (fs.existsSync(agentsSrc)) {
    fs.mkdirSync(agentsDest, { recursive: true });

    // Copy new agents
    const agentEntries = fs.readdirSync(agentsSrc, { withFileTypes: true });
    for (const entry of agentEntries) {
      if (entry.isFile() && entry.name.endsWith('.md')) {
        let content = fs.readFileSync(path.join(agentsSrc, entry.name), 'utf8');
        // Replace ~/.claude/ and $HOME/.claude/ as they are the source of truth in the repo
        const dirRegex = /~\/\.claude\//g;
        const homeDirRegex = /\$HOME\/\.claude\//g;
        const bareDirRegex = /~\/\.claude\b/g;
        const bareHomeDirRegex = /\$HOME\/\.claude\b/g;
        const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
        if (!isCopilot && !isAntigravity) {
          content = content.replace(dirRegex, pathPrefix);
          content = content.replace(homeDirRegex, pathPrefix);
          content = content.replace(bareDirRegex, normalizedPathPrefix);
          content = content.replace(bareHomeDirRegex, normalizedPathPrefix);
        }
        content = processAttribution(content, getCommitAttribution(runtime));
        // Convert frontmatter for runtime compatibility (agents need different handling)
        if (isOpencode) {
          // Resolve per-agent model for OpenCode agents.
          // Precedence: model_overrides[agent] > model_profile_overrides.opencode.<tier> > omit.
          // model_overrides (#2256): explicit per-agent override, highest precedence.
          // model_profile_overrides (#2794): tier-based runtime resolver, same parity as Codex.
          const _ocAgentName = entry.name.replace(/\.md$/, '');
          const _ocModelOverrides = readGsdEffectiveModelOverrides(targetDir);
          let _ocModelOverride = _ocModelOverrides?.[_ocAgentName] || null;
          if (!_ocModelOverride) {
            // Fall back to tier-based resolution via model_profile_overrides.opencode.<tier>.
            const _ocRuntimeResolver = readGsdRuntimeProfileResolver(targetDir);
            if (_ocRuntimeResolver) {
              const _ocEntry = _ocRuntimeResolver.resolve(_ocAgentName);
              if (_ocEntry?.model) {
                _ocModelOverride = _ocEntry.model;
              }
            }
          }
          content = convertClaudeToOpencodeFrontmatter(content, { isAgent: true, modelOverride: _ocModelOverride });
        } else if (isKilo) {
          content = convertClaudeToKiloFrontmatter(content, { isAgent: true });
        } else if (isGemini) {
          content = convertClaudeToGeminiAgent(content);
        } else if (isCodex) {
          content = convertClaudeAgentToCodexAgent(content);
        } else if (isCopilot) {
          content = convertClaudeAgentToCopilotAgent(content, isGlobal);
        } else if (isAntigravity) {
          content = convertClaudeAgentToAntigravityAgent(content, isGlobal);
        } else if (isCursor) {
          content = convertClaudeAgentToCursorAgent(content);
        } else if (isWindsurf) {
          content = convertClaudeAgentToWindsurfAgent(content);
        } else if (isAugment) {
          content = convertClaudeAgentToAugmentAgent(content);
        } else if (isTrae) {
          content = convertClaudeAgentToTraeAgent(content);
        } else if (isCodebuddy) {
          content = convertClaudeAgentToCodebuddyAgent(content);
        } else if (isCline) {
          content = convertClaudeAgentToClineAgent(content);
        } else if (isQwen) {
          content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
          content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
          content = content.replace(/\.claude\//g, '.qwen/');
        } else if (isHermes) {
          content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
          content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
          content = content.replace(/\.claude\//g, '.hermes/');
        }
        // #443 — Inject `effort:` into the Claude .md frontmatter ONLY.
        // Gemini/OpenCode/Qwen/Hermes also produce .md files but break on
        // unknown frontmatter keys (the repo bans skills:/permissionMode: for
        // the same reason — see tests/agent-frontmatter.test.cjs).
        // Claude Code reads per-subagent `effort:` frontmatter (anthropics/claude-code #31536).
        // Injection is per-runtime at install time because the canonical source
        // agents/*.md must stay Gemini-safe (no effort: key in source).
        if (runtime === 'claude') {
          const _effortCfg = readGsdEffectiveEffortConfig(targetDir);
          const _agentName = entry.name.replace(/\.md$/, '');
          const _universalEffort = resolveInstallTimeEffort(_effortCfg, _agentName);
          const _renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime('claude', _universalEffort).value;
          content = injectEffortFrontmatter(content, _renderedEffort);
        }
        // #3677 — normalize retired `/gsd:<cmd>` colon refs in the agent body
        // to the canonical hyphen form `/gsd-<cmd>` for hyphen-`name:`
        // runtimes (claude / qwen / hermes). Self-converting runtimes and
        // Gemini are skipped by the predicate — see
        // shouldNormalizeHyphenNamespaceInAgentBody above. Mirrors the
        // SKILL.md-body fix shipped via #3629.
        content = normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames());
        const destName = isCopilot ? entry.name.replace('.md', '.agent.md') : entry.name;
        fs.writeFileSync(path.join(agentsDest, destName), content);
      }
    }
    if (verifyInstalled(agentsDest, 'agents')) {
      console.log(`  ${green}✓${reset} Installed agents`);
    } else {
      failures.push('agents');
    }
  }

  // Copy CHANGELOG.md
  const changelogSrc = path.join(src, 'CHANGELOG.md');
  const changelogDest = path.join(targetDir, 'gsd-core', 'CHANGELOG.md');
  if (fs.existsSync(changelogSrc)) {
    fs.copyFileSync(changelogSrc, changelogDest);
    if (verifyFileInstalled(changelogDest, 'CHANGELOG.md')) {
      console.log(`  ${green}✓${reset} Installed CHANGELOG.md`);
    } else {
      failures.push('CHANGELOG.md');
    }
  }

  // Write VERSION file
  const versionDest = path.join(targetDir, 'gsd-core', 'VERSION');
  fs.writeFileSync(versionDest, pkg.version);
  if (verifyFileInstalled(versionDest, 'VERSION')) {
    console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
  } else {
    failures.push('VERSION');
  }

  if (!isCodex && !isCopilot && !isCursor && !isWindsurf && !isTrae && !isCline && !isKimi) {
    // Write package.json to force CommonJS mode for GSD scripts
    // Prevents "require is not defined" errors when project has "type": "module"
    // Node.js walks up looking for package.json - this stops inheritance from project
    const pkgJsonDest = path.join(targetDir, 'package.json');
    fs.writeFileSync(pkgJsonDest, '{"type":"commonjs"}\n');
    console.log(`  ${green}✓${reset} Wrote package.json (CommonJS mode)`);

    // Copy hooks from dist/ (bundled with dependencies)
    // Template paths for the target runtime (replaces '.claude' with correct config dir)
    const hooksSrc = path.join(src, 'hooks', 'dist');
    if (fs.existsSync(hooksSrc)) {
      const hooksDest = path.join(targetDir, 'hooks');
      fs.mkdirSync(hooksDest, { recursive: true });
      const hookEntries = fs.readdirSync(hooksSrc);
      const configDirReplacement = getConfigDirFromHome(runtime, isGlobal);
      for (const entry of hookEntries) {
        const srcFile = path.join(hooksSrc, entry);
        if (fs.statSync(srcFile).isFile()) {
          const destFile = path.join(hooksDest, entry);
          if (entry.endsWith('.js') || entry.endsWith('.cjs')) {
            let content = fs.readFileSync(srcFile, 'utf8');
            content = content.replace(/'\.claude'/g, configDirReplacement);
            content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
            content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
            if (isQwen) {
              content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
              content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
            }
            if (isHermes) {
              content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
              content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
            }
            // #376: rewrite gsd: → gsd- for hyphen-namespace runtimes
            if (shouldNormalizeHyphenNamespaceInAgentBody(runtime)) {
              content = content.replace(/gsd:/gi, 'gsd-');
            }
            content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
            fs.writeFileSync(destFile, content);
            try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
          } else {
            // non-.js: .sh hooks need {{GSD_VERSION}} stamped; others are copied as-is
            if (entry.endsWith('.sh')) {
              let content = fs.readFileSync(srcFile, 'utf8');
              content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
              fs.writeFileSync(destFile, content);
              try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows doesn't support chmod */ }
            } else {
              fs.copyFileSync(srcFile, destFile);
            }
          }
        } else if (fs.statSync(srcFile).isDirectory()) {
          // #3579: recurse one level into hook subdirs (lib/ etc.). The
          // graphify auto-update hook's rebuild helper lives at
          // hooks/dist/lib/gsd-graphify-rebuild.sh and must land at the
          // mirrored target path so the hook's REBUILD_SCRIPT lookup resolves.
          const subDest = path.join(hooksDest, entry);
          fs.mkdirSync(subDest, { recursive: true });
          const subEntries = fs.readdirSync(srcFile);
          for (const subEntry of subEntries) {
            const subSrcFile = path.join(srcFile, subEntry);
            if (!fs.statSync(subSrcFile).isFile()) continue;
            const subDestFile = path.join(subDest, subEntry);
            if (subEntry.endsWith('.sh')) {
              let content = fs.readFileSync(subSrcFile, 'utf8');
              content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
              fs.writeFileSync(subDestFile, content);
              try { fs.chmodSync(subDestFile, 0o755); } catch (e) { /* Windows */ }
            } else {
              fs.copyFileSync(subSrcFile, subDestFile);
            }
          }
        }
      }
      if (verifyInstalled(hooksDest, 'hooks')) {
        console.log(`  ${green}✓${reset} Installed hooks (bundled)`);
        // Warn if expected community .sh hooks are missing (non-fatal)
        const expectedShHooks = ['gsd-session-state.sh', 'gsd-validate-commit.sh', 'gsd-phase-boundary.sh', 'gsd-graphify-update.sh'];
        for (const sh of expectedShHooks) {
          if (!fs.existsSync(path.join(hooksDest, sh))) {
            console.warn(`  ${yellow}⚠${reset}  Missing expected hook: ${sh}`);
          }
        }
      } else {
        failures.push('hooks');
      }
    }
  }

  // Gate hooks/lib/ install on the same runtimes that receive hooks (see line ~8702).
  // Codex/Copilot/Cursor/Windsurf/Trae/Cline do not use the shared hooks/lib/ helpers
  // (Cursor uses standalone .js hook scripts registered via hooks.json; Codex uses
  // hooks.json directly; the others skip hooks entirely), so they must not receive
  // the hooks/lib/ helpers — otherwise the Codex comment downstream
  // ("we deliberately do *not* copy hooks/lib/ for Codex") is contradicted in practice.
  const hooksLibSrc = path.join(src, 'hooks', 'lib');
  if (!isCodex && !isCopilot && !isCursor && !isWindsurf && !isTrae && !isCline && !isKimi && fs.existsSync(hooksLibSrc)) {
    const hooksLibDest = path.join(targetDir, 'hooks', 'lib');
    fs.mkdirSync(hooksLibDest, { recursive: true });
    copyLibDir(hooksLibSrc, hooksLibDest, GSD_HOOK_LIB_FILES);
    console.log(`  ${green}✓${reset} Installed hooks/lib/ helpers (git-cmd, graphify-rebuild, ...)`);
  }

  // Install scripts/changeset/ and scripts/lib/ into <configDir>/scripts/
  // so that `node "$GSD_DIR/scripts/changeset/cli.cjs"` resolves at runtime.
  //
  // The changeset CLI (scripts/changeset/cli.cjs) is invoked by the update
  // workflow (gsd-core/workflows/update.md) to extract changelog ranges for
  // the /gsd-update preview step. It was previously only present in the npm
  // tarball root but never copied to the runtime config dir, causing the
  // preview to always silently fail (#935).
  //
  // cli.cjs requires:
  //   - sibling files in scripts/changeset/ (parse/render/serialize/github-release-notes)
  //   - ../lib/cli-exit.cjs  → scripts/lib/cli-exit.cjs
  //   - ../../gsd-core/bin/lib/semver-compare.cjs  (already installed under gsd-core/)
  //   - ../../gsd-core/bin/lib/package-identity.cjs (already installed under gsd-core/)
  //
  // All runtimes that use the update workflow need this, so we copy unconditionally
  // (same scope as gsd-core/ itself — every runtime that installs workflows gets it).
  const changesetSrc = path.join(src, 'scripts', 'changeset');
  const scriptsLibSrc = path.join(src, 'scripts', 'lib');
  if (!fs.existsSync(changesetSrc)) {
    // The changeset CLI source is missing from the package — mark as a hard failure
    // so the user knows the changelog preview will not work rather than silently degrading.
    failures.push('scripts/changeset/ (source missing from package — reinstall from npm)');
  } else {
    const changesetDest = path.join(targetDir, 'scripts', 'changeset');
    const scriptsLibDest = path.join(targetDir, 'scripts', 'lib');
    fs.mkdirSync(changesetDest, { recursive: true });
    fs.mkdirSync(scriptsLibDest, { recursive: true });
    // Copy scripts/changeset/ — all .cjs and .md files
    for (const entry of fs.readdirSync(changesetSrc)) {
      const srcFile = path.join(changesetSrc, entry);
      if (fs.statSync(srcFile).isFile()) {
        fs.copyFileSync(srcFile, path.join(changesetDest, entry));
      }
    }
    // Copy scripts/lib/ — cli-exit.cjs (required by cli.cjs) and any future lib helpers.
    // Hard-fail if missing: without cli-exit.cjs the installed CLI throws MODULE_NOT_FOUND.
    if (!fs.existsSync(scriptsLibSrc)) {
      failures.push('scripts/lib/ (source missing from package — reinstall from npm)');
    } else {
      for (const entry of fs.readdirSync(scriptsLibSrc)) {
        const srcFile = path.join(scriptsLibSrc, entry);
        if (fs.statSync(srcFile).isFile()) {
          fs.copyFileSync(srcFile, path.join(scriptsLibDest, entry));
        }
      }
      // Verify the critical dep cli-exit.cjs landed
      if (!verifyFileInstalled(path.join(scriptsLibDest, 'cli-exit.cjs'), 'scripts/lib/cli-exit.cjs')) {
        failures.push('scripts/lib/cli-exit.cjs');
      }
    }
    if (verifyFileInstalled(path.join(changesetDest, 'cli.cjs'), 'scripts/changeset/cli.cjs')) {
      console.log(`  ${green}✓${reset} Installed scripts/changeset/ (changelog preview CLI)`);
    } else {
      failures.push('scripts/changeset/cli.cjs');
    }
  }

  // Remove legacy get-shit-done-cc artifacts and stale update caches (#607).
  // cleanupLegacyGsdCc handles both the legacy shared cache and the per-package
  // cache (formerly an inline unlinkSync here). A cleanup failure must never
  // abort a successful install — log a warning and continue.
  // install() is never reached in --dry-run mode (the early-exit at the CLI
  // dispatch handles preview), so cleanup here always applies for real.
  try {
    cleanupLegacyGsdCc({ dryRun: false });
  } catch (cleanupErr) {
    console.warn(`  ${yellow}Warning: legacy cleanup failed: ${cleanupErr.message}${reset}`);
  }

  if (failures.length > 0) {
    console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
    process.exit(1);
  }

  // Write file manifest for future modification detection
  writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
  console.log(`  ${green}✓${reset} Wrote file manifest (${MANIFEST_NAME})`);

  // Report any backed-up local patches
  reportLocalPatches(targetDir, runtime);

  // Verify no leaked .claude paths in non-Claude runtimes (manifest-scoped)
  if (runtime !== 'claude') {
    const leakedPaths = [];
    // Only scan files that were written by this install (manifest-tracked).
    // Scanning the entire targetDir can match user-authored content that
    // legitimately references ~/.claude (e.g. personal notes), producing
    // false-positive warnings. Restricting to the manifest avoids that.
    let manifestFiles = null;
    try {
      const manifestPath = path.join(targetDir, MANIFEST_NAME);
      if (fs.existsSync(manifestPath)) {
        const manifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
        if (manifestData && typeof manifestData.files === 'object') {
          manifestFiles = Object.keys(manifestData.files);
        }
      }
    } catch (_manifestParseErr) {
      // If we cannot read/parse the manifest, skip the scan entirely to
      // avoid false positives rather than falling back to a full directory walk.
      manifestFiles = null;
    }
    if (manifestFiles !== null) {
      for (const relPath of manifestFiles) {
        const fileName = path.basename(relPath);
        if (!(fileName.endsWith('.md') || fileName.endsWith('.toml'))) continue;
        if (fileName === 'CHANGELOG.md') continue;
        const fullPath = path.join(targetDir, relPath);
        let content;
        try {
          content = fs.readFileSync(fullPath, 'utf8');
        } catch (err) {
          if (err.code === 'EPERM' || err.code === 'EACCES' || err.code === 'ENOENT') {
            continue; // skip inaccessible or missing files
          }
          throw err;
        }
        const matches = content.match(/(?:~|\$HOME)\/\.claude\b/g);
        if (matches) {
          leakedPaths.push({ file: relPath, count: matches.length });
        }
      }
    }
    if (leakedPaths.length > 0) {
      const totalLeaks = leakedPaths.reduce((sum, l) => sum + l.count, 0);
      console.warn(`\n  ${yellow}⚠${reset}  Found ${totalLeaks} unreplaced .claude path reference(s) in ${leakedPaths.length} file(s):`);
      for (const leak of leakedPaths.slice(0, 5)) {
        console.warn(`     ${dim}${leak.file}${reset} (${leak.count})`);
      }
      if (leakedPaths.length > 5) {
        console.warn(`     ${dim}... and ${leakedPaths.length - 5} more file(s)${reset}`);
      }
      console.warn(`  ${dim}These paths may not resolve correctly for ${runtimeLabel}.${reset}`);
    }
  }

  } catch (_earlyInstallErr) {
    // Installer Migration Module Phase 4: docs/installer-migrations.md
    // requires safe migrations to run before package materialization without
    // leaving stale state behind when materialization fails. Roll migration
    // actions back for every runtime; Codex then layers its broader runtime
    // snapshot rollback on top.
    rollbackInstallerMigrations();
    // #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();
    }
    throw _earlyInstallErr;
  }

  if (configIntent.installSurface === 'codex-toml' && !isMinimalMode(_effectiveInstallMode)) {
    // Capture pre-install snapshots before ANY GSD mutation
    // (#2760 fix 3). On post-write schema-validation failure OR any throw
    // during the mutation sequence (write failure, merge throw, etc.) we
    // restore these exact bytes so the user is never left with a broken
    // Codex CLI (#2760 fix 4 — extends snapshot coverage to write-failure
    // paths, paired with atomic temp-file writes in mergeCodexConfig and
    // the final hooks-write below).
    const codexConfigPathPreInstall = path.join(targetDir, 'config.toml');
    const codexConfigPreInstallSnapshot = fs.existsSync(codexConfigPathPreInstall)
      ? fs.readFileSync(codexConfigPathPreInstall)
      : null;
    const codexHooksJsonPathPreInstall = path.join(targetDir, 'hooks.json');
    const codexHooksJsonPreInstallSnapshot = fs.existsSync(codexHooksJsonPathPreInstall)
      ? fs.readFileSync(codexHooksJsonPathPreInstall)
      : null;
    const migrationTouchesHooksJson =
      !!(installerMigrationResult
        && installerMigrationResult.plan
        && Array.isArray(installerMigrationResult.plan.actions)
        && installerMigrationResult.plan.actions.some((action) => action && action.relPath === 'hooks.json'));

    // #3245 — unified idempotent rollback. Reverts ALL Codex-specific mutations:
    //   config.toml  — restore pre-install bytes (or remove if was absent)
    //   hooks.json   — restore pre-install bytes (or remove if was absent)
    //   skills/gsd-* — restore pre-existing dirs from content snapshot; remove
    //                   newly-created dirs (i.e. those not in the pre-install Set)
    //   agents/gsd-* — restore pre-existing files from content snapshot; remove
    //                   newly-created files
    //   gsd-core/VERSION — restore or remove
    //   *.tmp-*      — best-effort cleanup of installer-owned atomic-write temps
    //
    // Safe to call multiple times (idempotent): each remove/write is guarded by
    // existence checks. Safe to call before any snapshots are captured (variables
    // default to empty Set / null). Does NOT touch non-gsd-* user content.
    const restoreCodexSnapshot = () => {
      rollbackInstallerMigrations();
      // 1. config.toml
      if (codexConfigPreInstallSnapshot !== null) {
        try { fs.writeFileSync(codexConfigPathPreInstall, codexConfigPreInstallSnapshot); }
        catch (_) { /* best-effort restore — surface the original error */ }
      } else if (fs.existsSync(codexConfigPathPreInstall)) {
        try { fs.rmSync(codexConfigPathPreInstall); } catch (_) { /* best-effort */ }
      }

      // 1b. hooks.json
      // If installer migrations touched hooks.json, rollbackInstallerMigrations()
      // already restored the pre-migration file. Don't overwrite that state with
      // a post-migration snapshot.
      if (!migrationTouchesHooksJson) {
        if (codexHooksJsonPreInstallSnapshot !== null) {
          try { fs.writeFileSync(codexHooksJsonPathPreInstall, codexHooksJsonPreInstallSnapshot); }
          catch (_) { /* best-effort restore — surface the original error */ }
        } else if (fs.existsSync(codexHooksJsonPathPreInstall)) {
          try { fs.rmSync(codexHooksJsonPathPreInstall); } catch (_) { /* best-effort */ }
        }
      }

      // 2. skills/gsd-*
      //   • Dirs that pre-existed: wipe current contents, restore snapshotted files.
      //     The restore iterates the SNAPSHOT manifest (codexPreInstallSkillNames) rather
      //     than just the current filesystem so that dirs deleted during the install
      //     (copyCommandsAsCodexSkills removes pre-existing gsd-* dirs before re-writing)
      //     are restored even when they are absent from disk at rollback time (#3245 CR).
      //   • Dirs that did not pre-exist: remove entirely.
      const _rollbackSkillsDir = path.join(targetDir, 'skills');
      // Pass 1 — restore snapshot entries (may be absent from disk if deleted mid-install).
      for (const skillName of codexPreInstallSkillNames) {
        const skillDirPath = path.join(_rollbackSkillsDir, skillName);
        const fileMap = codexPreInstallSkillContents.get(skillName);
        try {
          fs.rmSync(skillDirPath, { recursive: true, force: true });
          fs.mkdirSync(skillDirPath, { recursive: true });
          if (fileMap) {
            for (const [relPath, buf] of fileMap) {
              const destFile = path.join(skillDirPath, relPath);
              try {
                fs.mkdirSync(path.dirname(destFile), { recursive: true });
                fs.writeFileSync(destFile, buf);
              } catch (_) { /* best-effort file restore */ }
            }
          }
        } catch (_) { /* best-effort dir restore */ }
      }
      // Pass 2 — remove any newly-created gsd-* dirs (not in the pre-install snapshot).
      if (fs.existsSync(_rollbackSkillsDir)) {
        try {
          for (const entry of fs.readdirSync(_rollbackSkillsDir, { withFileTypes: true })) {
            if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
            if (!codexPreInstallSkillNames.has(entry.name)) {
              // New dir written this session: remove entirely.
              try { fs.rmSync(path.join(_rollbackSkillsDir, entry.name), { recursive: true, force: true }); }
              catch (_) { /* best-effort */ }
            }
          }
        } catch (_) { /* best-effort */ }
      }

      // 3. agents/gsd-*.{md,toml}
      //   • Files that pre-existed: restore bytes from content snapshot.
      //     Iterates the SNAPSHOT manifest (codexPreInstallAgentFiles) so that files
      //     deleted by the pre-copy stale-removal pass (lines 7862-7870) are restored
      //     even when absent from disk at rollback time (#3245 CR).
      //   • Files that did not pre-exist: remove.
      const _rollbackAgentsDir = path.join(targetDir, 'agents');
      // Pass 1 — restore snapshot entries (may be absent from disk if deleted mid-install).
      for (const file of codexPreInstallAgentFiles) {
        const buf = codexPreInstallAgentContents.get(file);
        if (buf !== undefined) {
          try {
            fs.mkdirSync(_rollbackAgentsDir, { recursive: true });
            fs.writeFileSync(path.join(_rollbackAgentsDir, file), buf);
          } catch (_) { /* best-effort */ }
        }
      }
      // Pass 2 — remove any newly-created gsd-* agent files (not in the pre-install snapshot).
      if (fs.existsSync(_rollbackAgentsDir)) {
        try {
          for (const file of fs.readdirSync(_rollbackAgentsDir)) {
            if (!file.startsWith('gsd-') || (!file.endsWith('.md') && !file.endsWith('.toml'))) continue;
            if (!codexPreInstallAgentFiles.has(file)) {
              // New file written this session: remove.
              try { fs.unlinkSync(path.join(_rollbackAgentsDir, file)); } catch (_) { /* best-effort */ }
            }
          }
        } catch (_) { /* best-effort */ }
      }

      // 4. gsd-core/VERSION
      const _rollbackVersionPath = path.join(targetDir, 'gsd-core', 'VERSION');
      if (codexPreInstallVersionBytes !== null) {
        try { fs.writeFileSync(_rollbackVersionPath, codexPreInstallVersionBytes); }
        catch (_) { /* best-effort */ }
      } else if (fs.existsSync(_rollbackVersionPath)) {
        try { fs.unlinkSync(_rollbackVersionPath); } catch (_) { /* best-effort */ }
      }

      // 5. Orphaned atomic-write temp files (<file>.tmp-<pid>-<n>) in targetDir.
      // These can accumulate if an atomic write fails mid-rename. Best-effort scan.
      //
      // Only delete temp files whose absolute path is in __atomicWrittenTmps —
      // the Set populated by atomicWriteFileSync for every temp this installer
      // process actually created. This scopes cleanup to installer-owned writes
      // and avoids clobbering unrelated tools' temp files that happen to match
      // the same *.tmp-<pid>-<n> suffix pattern.
      const _tmpPattern = /\.tmp-\d+-\d+$/;
      function _cleanTmpFiles(dir) {
        if (!fs.existsSync(dir)) return;
        let entries;
        try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
        for (const entry of entries) {
          const full = path.join(dir, entry.name);
          if (entry.isDirectory()) {
            _cleanTmpFiles(full);
          } else if (_tmpPattern.test(entry.name) && __atomicWrittenTmps.has(full)) {
            try { fs.unlinkSync(full); } catch (_) { /* best-effort */ }
          }
        }
      }
      _cleanTmpFiles(targetDir);
    };

    let agentCount = 0;
    if (!isMinimalMode(_effectiveInstallMode)) {
      try {
        // Generate Codex config.toml and per-agent .toml files.
        agentCount = installCodexConfig(targetDir, agentsSrc);
      } catch (e) {
        restoreCodexSnapshot();
        throw e;
      }
      console.log(`  ${green}✓${reset} Generated config.toml with ${agentCount} agent roles`);
      console.log(`  ${green}✓${reset} Generated ${agentCount} agent .toml config files`);
      // Re-write the manifest now that .toml agent files exist on disk.
      // The initial writeManifest call (before Codex config generation) could
      // not include agents/gsd-*.toml because those files did not yet exist.
      writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
    } else {
      console.log(`  ${dim}↳${reset} Skipping Codex agent config generation (minimal install)`);
    }

    // Copy only the hook files that Codex actually registers via its hook configuration (#2153).
    // #772: added gsd-context-monitor.js for the new SubagentStart/Stop/PostToolUse events.
    // We deliberately do *not* copy gsd-graphify-update.sh or hooks/lib/ for Codex
    // in this change (graphify auto-update support for Codex is out of scope for #3579).
    const CODEX_HOOKS_TO_COPY = ['gsd-check-update.js', 'gsd-context-monitor.js'];
    const codexHooksSrc = path.join(src, 'hooks', 'dist');
    if (fs.existsSync(codexHooksSrc)) {
      const codexHooksDest = path.join(targetDir, 'hooks');
      fs.mkdirSync(codexHooksDest, { recursive: true });
      const configDirReplacement = getConfigDirFromHome(runtime, isGlobal);
      for (const entry of fs.readdirSync(codexHooksSrc)) {
        if (!CODEX_HOOKS_TO_COPY.includes(entry)) continue;
        const srcFile = path.join(codexHooksSrc, entry);
        if (!fs.statSync(srcFile).isFile()) continue;
        const destFile = path.join(codexHooksDest, entry);
        if (entry.endsWith('.js')) {
          let content = fs.readFileSync(srcFile, 'utf8');
          content = content.replace(/'\.claude'/g, configDirReplacement);
          content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
          content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
          content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
          fs.writeFileSync(destFile, content);
          try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
        } else if (entry.endsWith('.sh')) {
          // #2136: any .sh hook reaching this loop must have {{GSD_VERSION}}
          // stamped so installed scripts carry a concrete version header and
          // stale-hook detection keeps working across upgrades. The current
          // CODEX_HOOKS_TO_COPY allowlist excludes .sh files, so this branch
          // is defensive — it preserves the invariant if the allowlist is
          // extended later (e.g. to ship gsd-graphify-update.sh for Codex).
          let content = fs.readFileSync(srcFile, 'utf8');
          content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
          fs.writeFileSync(destFile, content);
          try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
        }
      }
      console.log(`  ${green}✓${reset} Installed hooks (Codex)`);
    }

    // Add Codex hooks (SessionStart for update checking) — requires codex_hooks feature flag
    const configPath = path.join(targetDir, 'config.toml');
    // Use the pre-install snapshot captured before installCodexConfig ran so
    // restore returns the file to its true pre-GSD state on validation
    // failure (#2760 fix 3) — not to the post-agent-merge state.
    const preWriteBackup = codexConfigPreInstallSnapshot;
    try {
      let configContent = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf-8') : '';
      const eol = detectLineEnding(configContent);

      // Strip ALL prior GSD-managed hook blocks BEFORE migration so the migration
      // only touches user-authored hooks, not GSD-owned stale entries. Running
      // strip after migration causes Shape 1 (legacy gsd-update-check filename)
      // to be converted by migration before the strip regex can match it (#2698).
      //
      // Historical shapes stripped, in order:
      //   Shape 1 — legacy gsd-update-check filename (pre-#1755): flat [[hooks]] + event
      //   Shape 2 — flat [[hooks]] + event = "SessionStart" (#2637 era, never correct)
      //   Shape 4 — correct two-block nested (strip before shape 3 to avoid orphaned header)
      //   Shape 3 — single-block [[hooks.SessionStart]] without nested .hooks (#2760 era)
      configContent = stripStaleGsdHookBlocks(configContent);

      // Migrate legacy [hooks] map format and flat [[hooks]] AoT entries to the
      // namespaced [[hooks.<EVENT>]] form after stripping GSD-managed stale blocks.
      // Running migration after strip ensures only user-authored hooks are migrated
      // (#2698 regression: migration before strip converts stale GSD blocks before
      // the strip regexes can match their original shape).
      const migratedContent = migrateCodexHooksMapFormat(configContent);
      if (migratedContent !== configContent) {
        configContent = migratedContent;
        console.log(`  ${green}✓${reset} Migrated legacy Codex [hooks] format to two-level nested AoT`);
      }

      const codexHooksFeature = ensureCodexHooksFeature(configContent);
      configContent = setManagedCodexHooksOwnership(codexHooksFeature.content, codexHooksFeature.ownership);

      // GSD-managed Codex hook payloads now live in hooks.json to avoid mixed
      // representation warnings when a single layer contains both hooks.json
      // and inline [hooks] entries. Keep config.toml focused on feature flags
      // and agent metadata.
      const codexNodeRunner = resolveNodeRunner();

      // #2760 fix 3 — post-write schema validation. Parse the bytes we are
      // about to commit and assert they match Codex's expected shape. If
      // validation fails we restore the pre-install backup and abort so the
      // user is never left with a Codex CLI that won't load.
      // Test seam: tests can inject `__codexSchemaValidator` to force the
      // validator to fail and exercise the restore-and-abort path.
      const validatorFn = (typeof module !== 'undefined' && module.exports && module.exports.__codexSchemaValidator)
        ? module.exports.__codexSchemaValidator
        : validateCodexConfigSchema;
      const validation = validatorFn(configContent);
      if (!validation.ok) {
        restoreCodexSnapshot();
        throw new Error(
          `post-write Codex schema validation failed: ${validation.reason}. ` +
          `Restored ${preWriteBackup !== null ? 'pre-install backup' : 'empty state'}.`
        );
      }

      // Atomic write (#2760 fix 4) — write to a sibling temp file, then
      // renameSync over the target. A mid-write failure cannot truncate the
      // existing config; the snapshot restore below is a second line of
      // defense if even the rename fails.
      try {
        atomicWriteFileSync(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
        // aborts with a clear error rather than warn-and-continue (which
        // produced "Done!" with no Codex agents configured).
        restoreCodexSnapshot();
        const wrapped = new Error(
          `post-write Codex install failed: ${writeErr && writeErr.message ? writeErr.message : String(writeErr)}. ` +
          `Restored ${preWriteBackup !== null ? 'pre-install backup' : 'empty state'}.`
        );
        throw wrapped;
      }
      if (hasEnabledCodexHooksFeature(configContent)) {
        const checkUpdateFile = path.join(targetDir, 'hooks', 'gsd-check-update.js');
        if (!fs.existsSync(checkUpdateFile)) {
          console.warn(`  ${yellow}⚠${reset}  Skipped Codex SessionStart hook registration — gsd-check-update.js not found at target`);
        } else if (!codexNodeRunner) {
          console.warn(`  ${yellow}⚠${reset}  Skipping Codex SessionStart hook registration — Node executable path unavailable (process.execPath is empty). See #2979 / #3002 / #3017.`);
        } else {
          const hookWrite = ensureCodexHooksJsonSessionStart(targetDir, {
            absoluteRunner: codexNodeRunner,
            platform: process.platform,
          });
          if (hookWrite.wrote) {
            console.log(`  ${green}✓${reset} Configured Codex hooks (SessionStart via hooks.json)`);
          } else {
            console.log(`  ${green}✓${reset} Verified Codex hooks (SessionStart via hooks.json)`);
          }
        }

        // ── Codex extended hook events (#772) ────────────────────────────────
        // Codex CLI stabilised a full hook-event set in rust-v0.137.0. Register
        // three new high-value lifecycle events — all routed through
        // gsd-context-monitor.js so context-headroom warnings surface at:
        //   SubagentStart — subagent session open (environment / agent-name aware)
        //   Stop          — model stop / session final-response moment
        //   PostToolUse   — after each tool invocation (mirrors Claude baseline)
        //
        // Note: UserPromptSubmit is NOT wired — gsd-prompt-guard exits unless
        // tool_name is Write|Edit (PreToolUse payload shape), so it would be a
        // silent no-op for the UserPromptSubmit payload.  Registration deferred
        // to a follow-on issue.
        //
        // Guard: only register when the context-monitor file exists and the node
        // runner is available — same guards as the SessionStart path above.
        const contextMonitorFile = path.join(targetDir, 'hooks', 'gsd-context-monitor.js');
        if (codexNodeRunner && fs.existsSync(contextMonitorFile)) {
          for (const codexEvent of ['SubagentStart', 'Stop', 'PostToolUse']) {
            const eventWrite = ensureCodexHooksJsonEvent(targetDir, codexEvent, {
              absoluteRunner: codexNodeRunner,
              platform: process.platform,
            });
            if (eventWrite.wrote) {
              console.log(`  ${green}✓${reset} Configured Codex hooks (${codexEvent} via hooks.json)`);
            } else if (eventWrite.changed) {
              console.log(`  ${green}✓${reset} Verified Codex hooks (${codexEvent} via hooks.json)`);
            }
          }
        } else if (!codexNodeRunner) {
          console.warn(`  ${yellow}⚠${reset}  Skipped Codex SubagentStart/Stop/PostToolUse hook registration — Node runner unavailable.`);
        }
        // ── end Codex extended hook events ────────────────────────────────────
      }
    } catch (e) {
      // #2760 — schema-validation and write failures must be loud and fatal
      // so the user is never left with a config Codex refuses to load (or no
      // Codex agents configured at all). The pre-install snapshot restore has
      // already run for write-side throws via the inner catch above and via
      // restoreCodexSnapshot in the validation branch.
      if (e && typeof e.message === 'string' && e.message.startsWith('post-write')) {
        console.error(`  ${red}✗${reset} ${e.message}`);
        throw e;
      }
      // #2760 CR5 finding 1 — pre-write failures (migrateCodexHooksMapFormat,
      // ensureCodexHooksFeature, config reads, configContent construction,
      // etc.) must ALSO be fatal. Previously this branch downgraded to a
      // console.warn, leaving the install to print "Done!" with no Codex
      // hooks configured — same defect class as finding 1, different layer.
      // Restore the pre-install snapshot and rethrow so the outer install
      // pipeline aborts.
      restoreCodexSnapshot();
      const wrapped = new Error(
        `Codex hook configuration failed (pre-write): ${e && e.message ? e.message : String(e)}. ` +
          `Restored ${preWriteBackup !== null ? 'pre-install backup' : 'empty state'}.`
      );
      console.error(`  ${red}✗${reset} ${wrapped.message}`);
      throw wrapped;
    }

    persistActiveProfileMarker();
    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
  }

  if (configIntent.installSurface === 'copilot-instructions') {
    // Generate copilot-instructions.md
    const templatePath = path.join(targetDir, 'gsd-core', 'templates', 'copilot-instructions.md');
    const instructionsPath = path.join(targetDir, 'copilot-instructions.md');
    if (fs.existsSync(templatePath)) {
      const template = fs.readFileSync(templatePath, 'utf8');
      mergeCopilotInstructions(instructionsPath, template);
      console.log(`  ${green}✓${reset} Generated copilot-instructions.md`);
      // #786: also emit AGENTS.md, which Copilot CLI reads as primary
      // instructions from the repository root. AGENTS.md is a repo-root concept
      // (no documented user-scope home), so emit it only for local installs;
      // global scope is already covered by ~/.copilot/copilot-instructions.md.
      if (!isGlobal) {
        const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
        mergeCopilotInstructions(agentsMdPath, template);
        console.log(`  ${green}✓${reset} Generated AGENTS.md`);
      }
    }
    // #786: emit a self-contained Copilot lifecycle hook (sessionStart). Copilot
    // command hooks run inline bash/powershell, so this needs no separate hook
    // script and cannot dangle. Repo scope → .github/hooks/, user → ~/.copilot/hooks/.
    // The hook is a required install artifact, so a write failure is fatal (it
    // propagates) rather than silently producing a "successful" install missing
    // the feature.
    writeCopilotHookConfig(targetDir);
    console.log(`  ${green}✓${reset} Configured Copilot lifecycle hook (sessionStart)`);
    persistActiveProfileMarker();
    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
  }

  if (configIntent.installSurface === 'cursor-hooks-json') {
    // #777: Cursor v2.4+ supports hooks.json. Register sessionStart + postToolUse.
    // Hook scripts are copied to <targetDir>/hooks/ and referenced by hooks.json.
    const cursorHookResult = writeCursorHooksJson(targetDir, src, {});
    if (cursorHookResult.changed) {
      console.log(`  ${green}✓${reset} Configured Cursor lifecycle hooks (sessionStart, postToolUse)`);
    } else {
      console.log(`  ${green}✓${reset} Cursor lifecycle hooks already up to date`);
    }
    // Re-run the manifest pass so the hook scripts + hooks.json are hash-tracked.
    writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
    persistActiveProfileMarker();
    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
  }

  if (configIntent.installSurface === 'profile-marker-only') {
    // Windsurf/Trae/Kimi use artifact-only surfaces — no config.toml or settings.json hooks needed.
    persistActiveProfileMarker();
    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
  }

  if (configIntent.installSurface === 'cline-rules') {
    // Cline uses the `.clinerules/` directory form (issue #787): GSD rules live
    // at .clinerules/gsd.md and a PreToolUse lifecycle hook at
    // .clinerules/hooks/PreToolUse. Global installs also get ~/.agents/AGENTS.md.
    writeClineArtifacts(targetDir, isGlobal);
    // Re-run the manifest pass: these artifacts are written *after* the earlier
    // writeManifest() call, so a second pass is needed to hash-track them.
    writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
    persistActiveProfileMarker();
    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
  }

  // Configure statusline and hooks in settings.json (or settings.local.json for local Claude installs).
  // Gemini and Antigravity use AfterTool instead of PostToolUse for post-tool hooks
  const postToolEvent = (runtime === 'gemini' || runtime === 'antigravity') ? 'AfterTool' : 'PostToolUse';
  // #338: local Claude installs write to settings.local.json (Claude Code's per-user/gitignored slot)
  // so engineer-specific absolute paths (Node binary, home dir) never land in the repo-shared
  // settings.json. Global installs and all other runtimes continue to use settings.json.
  const isLocalClaude = (runtime === 'claude' && !isGlobal);
  const settingsFileName = isLocalClaude ? 'settings.local.json' : 'settings.json';
  const settingsPath = path.join(targetDir, settingsFileName);

  // #338 migration: if a prior local Claude install wrote GSD-shaped entries to settings.json,
  // relocate them to settings.local.json and clear them from the shared file in the same run.
  if (isLocalClaude) {
    const sharedSettingsPath = path.join(targetDir, 'settings.json');
    const sharedRaw = readSettings(sharedSettingsPath);
    if (sharedRaw && typeof sharedRaw === 'object') {
      const hasGsdHooks = sharedRaw.hooks && Object.values(sharedRaw.hooks).some(
        entries => Array.isArray(entries) && entries.some(
          entry => entry && entry.hooks && Array.isArray(entry.hooks) && entry.hooks.some(
            h => h && typeof h.command === 'string' && isManagedHookCommand(h.command, { surface: 'settings-json' })
          )
        )
      );
      const hasGsdStatusline = sharedRaw.statusLine && sharedRaw.statusLine.command &&
        isManagedHookCommand(sharedRaw.statusLine.command, { surface: 'settings-json' });
      if (hasGsdHooks || hasGsdStatusline) {
        // Merge GSD entries into settings.local.json
        const localRaw = readSettings(settingsPath) || {};
        if (hasGsdStatusline && !localRaw.statusLine) {
          localRaw.statusLine = sharedRaw.statusLine;
        }
        if (hasGsdHooks) {
          if (!localRaw.hooks) localRaw.hooks = {};
          for (const [eventName, entries] of Object.entries(sharedRaw.hooks || {})) {
            if (!Array.isArray(entries)) continue;
            const gsdEntries = entries.filter(
              entry => entry && entry.hooks && Array.isArray(entry.hooks) && entry.hooks.some(
                h => h && typeof h.command === 'string' && isManagedHookCommand(h.command, { surface: 'settings-json' })
              )
            );
            if (gsdEntries.length > 0) {
              if (!localRaw.hooks[eventName]) localRaw.hooks[eventName] = [];
              // Only merge entries not already present in local
              for (const entry of gsdEntries) {
                const alreadyPresent = localRaw.hooks[eventName].some(
                  le => le && le.hooks && Array.isArray(le.hooks) && le.hooks.some(
                    lh => lh && entry.hooks.some(eh => eh && eh.command === lh.command)
                  )
                );
                if (!alreadyPresent) localRaw.hooks[eventName].push(entry);
              }
            }
          }
        }
        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
        writeSettings(settingsPath, localRaw);

        // Remove GSD entries from shared settings.json
        if (hasGsdStatusline) {
          delete sharedRaw.statusLine;
        }
        if (hasGsdHooks) {
          for (const [eventName, entries] of Object.entries(sharedRaw.hooks || {})) {
            if (!Array.isArray(entries)) continue;
            sharedRaw.hooks[eventName] = entries.filter(
              entry => !(entry && entry.hooks && Array.isArray(entry.hooks) && entry.hooks.some(
                h => h && typeof h.command === 'string' && isManagedHookCommand(h.command, { surface: 'settings-json' })
              ))
            );
            if (sharedRaw.hooks[eventName].length === 0) {
              delete sharedRaw.hooks[eventName];
            }
          }
          if (sharedRaw.hooks && Object.keys(sharedRaw.hooks).length === 0) {
            delete sharedRaw.hooks;
          }
        }
        writeSettings(sharedSettingsPath, sharedRaw);
        console.log(`  ${green}✓${reset} Migrated GSD hook entries from settings.json to settings.local.json (#338)`);
      }
    }
  }

  const rawSettings = readSettings(settingsPath);
  if (rawSettings === null) {
    console.log('  ' + yellow + 'i' + reset + '  Skipping settings.local.json configuration — file could not be parsed (comments or malformed JSON). Your existing settings are preserved.');
    persistActiveProfileMarker();
    return;
  }
  const settings = validateHookFields(cleanupOrphanedHooks(rawSettings));
  // #3002 CR: rewrite legacy `node .../gsd-*.js` command strings carried over
  // from pre-#2979 installs to use the absolute node binary path. Without this,
  // existing managed hook entries stay bare-`node`-prefixed across reinstalls
  // and remain broken under GUI/minimal-PATH runtimes.
  const settingsRunner = resolveNodeRunner();
  if (settingsRunner && rewriteLegacyManagedNodeHookCommands(settings, settingsRunner, { platform: process.platform, runtime })) {
    console.log(`  ${green}✓${reset} Rewrote legacy bare-node managed-hook commands to absolute path (#2979)`);
  }
  // Local installs anchor hook paths so they resolve regardless of cwd (#1906).
  // Claude Code sets $CLAUDE_PROJECT_DIR; Gemini/Antigravity do not — and on
  // Windows their own substitution logic doubles the path (#2557). Those runtimes
  // run project hooks with the project dir as cwd, so bare relative paths work.
  const localPrefix = projectLocalHookPrefix({ runtime, dirName });
  const hookOpts = { portableHooks: hasPortableHooks, runtime };
  // #2979: local-install hook commands also use the absolute node path so
  // GUI/minimal-PATH runtimes can resolve them. Bare `node` fails when the
  // host launches the runtime with a stripped PATH (Finder/Antigravity/etc).
  const localNodeRunner = resolveNodeRunner();
  const localBashRunner = resolveBashRunner({ platform: process.platform });
  // If we cannot resolve an absolute node path AND this is a local install,
  // skip managed-hook registration. Returning null from buildHookCommand on
  // global installs has the same effect. Better to skip than to emit a bare
  // `node` command that recreates the #2979 failure.
  const localCmd = (hookFile) => localNodeRunner === null
    ? null
    : projectShellCommandText({
      runnerToken: localNodeRunner,
      argTokens: [`${localPrefix}/hooks/${hookFile}`],
      runtime,
      platform: process.platform,
    });
  const localShellCmd = (hookFile) => buildLocalShellHookCommand({
    localPrefix,
    hookFile,
    bashRunner: localBashRunner,
    runtime,
    platform: process.platform,
  });
  const statuslineCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-statusline.js', hookOpts)
    : localCmd('gsd-statusline.js');
  const updateCheckCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-check-update.js', hookOpts)
    : localCmd('gsd-check-update.js');
  const contextMonitorCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-context-monitor.js', hookOpts)
    : localCmd('gsd-context-monitor.js');
  const promptGuardCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-prompt-guard.js', hookOpts)
    : localCmd('gsd-prompt-guard.js');
  const readGuardCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-read-guard.js', hookOpts)
    : localCmd('gsd-read-guard.js');
  const readInjectionScannerCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-read-injection-scanner.js', hookOpts)
    : localCmd('gsd-read-injection-scanner.js');
  const configReloadCommand = isGlobal
    ? buildHookCommand(targetDir, 'gsd-config-reload.js', hookOpts)
    : localCmd('gsd-config-reload.js');

  // #3002 CR: when resolveNodeRunner() returns null, every dependent JS-hook
  // command is null too. Emit one warning here so the operator sees the cause
  // ONCE instead of per-hook. Each registration site below also guards on its
  // own *Command variable being truthy, so we never write `command: null`
  // entries to settings.json (which the runtime's hook schema would reject).
  const anyJsHookCommandNull = !statuslineCommand
    || !updateCheckCommand
    || !contextMonitorCommand
    || !promptGuardCommand
    || !readGuardCommand
    || !readInjectionScannerCommand;
  if (anyJsHookCommandNull) {
    console.warn(`  ${yellow}⚠${reset}  Skipping managed JS hook registration — Node executable path unavailable (process.execPath is empty). See #2979 / #3002.`);
  }

  // Enable experimental agents for Gemini CLI (required for custom sub-agents)
  if (isGemini) {
    if (!settings.experimental) {
      settings.experimental = {};
    }
    if (!settings.experimental.enableAgents) {
      settings.experimental.enableAgents = true;
      console.log(`  ${green}✓${reset} Enabled experimental agents`);
    }
  }

  // Configure SessionStart hook for update checking (skip for opencode)
  if (!isOpencode && !isKilo) {
    if (!settings.hooks) {
      settings.hooks = {};
    }
    if (!settings.hooks.SessionStart) {
      settings.hooks.SessionStart = [];
    }

    const hasGsdUpdateHook = settings.hooks.SessionStart.some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-check-update'))
    );

    // Guard: only register if the hook file was actually installed (#1754).
    // When hooks/dist/ is missing from the npm package (as in v1.32.0), the
    // copy step produces no files but the registration step ran unconditionally,
    // causing "hook error" on every tool invocation.
    const checkUpdateFile = path.join(targetDir, 'hooks', 'gsd-check-update.js');
    if (!hasGsdUpdateHook && fs.existsSync(checkUpdateFile) && updateCheckCommand) {
      settings.hooks.SessionStart.push({
        hooks: [
          {
            type: 'command',
            command: updateCheckCommand
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured update check hook`);
    } else if (!hasGsdUpdateHook && !fs.existsSync(checkUpdateFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped update check hook — gsd-check-update.js not found at target`);
    }

    // Configure post-tool hook for context window monitoring
    if (!settings.hooks[postToolEvent]) {
      settings.hooks[postToolEvent] = [];
    }

    const hasContextMonitorHook = settings.hooks[postToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-context-monitor'))
    );

    const contextMonitorFile = path.join(targetDir, 'hooks', 'gsd-context-monitor.js');
    if (!hasContextMonitorHook && fs.existsSync(contextMonitorFile) && contextMonitorCommand) {
      settings.hooks[postToolEvent].push({
        matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task',
        hooks: [
          {
            type: 'command',
            command: contextMonitorCommand,
            timeout: 10
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured context window monitor hook`);
    } else if (!hasContextMonitorHook && !fs.existsSync(contextMonitorFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped context monitor hook — gsd-context-monitor.js not found at target`);
    } else {
      // Migrate existing context monitor hooks: add matcher and timeout if missing
      for (const entry of settings.hooks[postToolEvent]) {
        if (entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-context-monitor'))) {
          let migrated = false;
          if (!entry.matcher) {
            entry.matcher = 'Bash|Edit|Write|MultiEdit|Agent|Task';
            migrated = true;
          }
          for (const h of entry.hooks) {
            if (h.command && h.command.includes('gsd-context-monitor') && !h.timeout) {
              h.timeout = 10;
              migrated = true;
            }
          }
          if (migrated) {
            console.log(`  ${green}✓${reset} Updated context monitor hook (added matcher + timeout)`);
          }
        }
      }
    }

    // Configure PreToolUse hook for prompt injection detection
    // Gemini and Antigravity use BeforeTool instead of PreToolUse for pre-tool hooks
    const preToolEvent = (runtime === 'gemini' || runtime === 'antigravity') ? 'BeforeTool' : 'PreToolUse';
    if (!settings.hooks[preToolEvent]) {
      settings.hooks[preToolEvent] = [];
    }

    const hasPromptGuardHook = settings.hooks[preToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-prompt-guard'))
    );

    const promptGuardFile = path.join(targetDir, 'hooks', 'gsd-prompt-guard.js');
    if (!hasPromptGuardHook && fs.existsSync(promptGuardFile) && promptGuardCommand) {
      settings.hooks[preToolEvent].push({
        matcher: 'Write|Edit',
        hooks: [
          {
            type: 'command',
            command: promptGuardCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured prompt injection guard hook`);
    } else if (!hasPromptGuardHook && !fs.existsSync(promptGuardFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped prompt guard hook — gsd-prompt-guard.js not found at target`);
    }

    // Configure PreToolUse hook for read-before-edit guidance (#1628)
    // Prevents infinite retry loops when non-Claude models attempt to edit
    // files without reading them first. Advisory-only — does not block.
    const hasReadGuardHook = settings.hooks[preToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-read-guard'))
    );

    const readGuardFile = path.join(targetDir, 'hooks', 'gsd-read-guard.js');
    if (!hasReadGuardHook && fs.existsSync(readGuardFile) && readGuardCommand) {
      settings.hooks[preToolEvent].push({
        matcher: 'Write|Edit',
        hooks: [
          {
            type: 'command',
            command: readGuardCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured read-before-edit guard hook`);
    } else if (!hasReadGuardHook && !fs.existsSync(readGuardFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped read guard hook — gsd-read-guard.js not found at target`);
    }

    // Configure PostToolUse hook for read-time prompt injection scanning (#2201)
    // Scans content returned by the Read tool for injection patterns, including
    // summarisation-specific patterns that survive context compression.
    const hasReadInjectionScannerHook = settings.hooks[postToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-read-injection-scanner'))
    );

    const readInjectionScannerFile = path.join(targetDir, 'hooks', 'gsd-read-injection-scanner.js');
    if (!hasReadInjectionScannerHook && fs.existsSync(readInjectionScannerFile) && readInjectionScannerCommand) {
      settings.hooks[postToolEvent].push({
        matcher: 'Read',
        hooks: [
          {
            type: 'command',
            command: readInjectionScannerCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured read injection scanner hook`);
    } else if (!hasReadInjectionScannerHook && !fs.existsSync(readInjectionScannerFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped read injection scanner hook — gsd-read-injection-scanner.js not found at target`);
    }

    // Community hooks — registered on install but opt-in at runtime.
    // Each hook checks .planning/config.json for hooks.community: true
    // and exits silently (no-op) if not enabled. This lets users enable
    // them per-project by adding: "hooks": { "community": true }

    // Configure workflow guard hook (opt-in via hooks.workflow_guard: true)
    // Detects file edits outside GSD workflow context and advises using
    // /gsd-quick or /gsd-fast for state-tracked changes. Also hard-blocks
    // unsafe Bash commands that violate worktree-agent isolation.
    const workflowGuardCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-workflow-guard.js', hookOpts)
      : localCmd('gsd-workflow-guard.js');
    const workflowGuardMatcher = 'Bash|Edit|Write|MultiEdit';
    const workflowGuardHookEntry = settings.hooks[preToolEvent].find(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-workflow-guard'))
    );
    const hasWorkflowGuardHook = Boolean(workflowGuardHookEntry);

    const workflowGuardFile = path.join(targetDir, 'hooks', 'gsd-workflow-guard.js');
    if (hasWorkflowGuardHook && workflowGuardHookEntry.matcher !== workflowGuardMatcher) {
      workflowGuardHookEntry.matcher = workflowGuardMatcher;
      console.log(`  ${green}✓${reset} Updated workflow guard hook matcher`);
    } else if (!hasWorkflowGuardHook && fs.existsSync(workflowGuardFile) && workflowGuardCommand) {
      settings.hooks[preToolEvent].push({
        matcher: workflowGuardMatcher,
        hooks: [
          {
            type: 'command',
            command: workflowGuardCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured workflow guard hook (opt-in via hooks.workflow_guard)`);
    } else if (!hasWorkflowGuardHook && !fs.existsSync(workflowGuardFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped workflow guard hook — gsd-workflow-guard.js not found at target`);
    }

    // Configure PreToolUse hook for worktree absolute-path safety (#260)
    // Hard-blocks Edit/Write/MultiEdit tool calls with absolute paths that resolve
    // outside the current worktree root. Prevents executor agents from
    // accidentally writing to the main checkout when running in isolation="worktree".
    const worktreePathGuardCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-worktree-path-guard.js', hookOpts)
      : localCmd('gsd-worktree-path-guard.js');
    const hasWorktreePathGuardHook = settings.hooks[preToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-worktree-path-guard'))
    );
    const worktreePathGuardFile = path.join(targetDir, 'hooks', 'gsd-worktree-path-guard.js');
    if (!hasWorktreePathGuardHook && fs.existsSync(worktreePathGuardFile) && worktreePathGuardCommand) {
      settings.hooks[preToolEvent].push({
        matcher: 'Write|Edit|MultiEdit',
        hooks: [
          {
            type: 'command',
            command: worktreePathGuardCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured worktree path guard hook`);
    } else if (!hasWorktreePathGuardHook && !fs.existsSync(worktreePathGuardFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped worktree path guard hook — gsd-worktree-path-guard.js not found at target`);
    }

    // Configure commit validation hook (Conventional Commits enforcement, opt-in)
    const validateCommitCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-validate-commit.sh', hookOpts)
      : localShellCmd('gsd-validate-commit.sh');
    const hasValidateCommitHook = settings.hooks[preToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-validate-commit'))
    );
    // Guard: only register if the .sh file was actually installed. If the npm package
    // omitted the file (as happened in v1.32.0, bug #1817), registering a missing hook
    // causes a hook error on every Bash tool invocation.
    const validateCommitFile = path.join(targetDir, 'hooks', 'gsd-validate-commit.sh');
    if (!hasValidateCommitHook && fs.existsSync(validateCommitFile) && validateCommitCommand) {
      settings.hooks[preToolEvent].push({
        matcher: 'Bash',
        hooks: [
          {
            type: 'command',
            command: validateCommitCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured commit validation hook (opt-in via config)`);
    } else if (!hasValidateCommitHook && !fs.existsSync(validateCommitFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped commit validation hook — gsd-validate-commit.sh not found at target`);
    } else if (!hasValidateCommitHook && !validateCommitCommand) {
      console.warn(`  ${yellow}⚠${reset}  Skipped commit validation hook — Bash executable path unavailable (#3393)`);
    }

    // Configure graphify auto-update hook (opt-in via graphify.auto_update; default false, #3347).
    // PostToolUse Bash matcher — fires after git commit/merge/pull/rebase --continue/cherry-pick
    // on the default branch, dispatches `graphify update .` in a detached subprocess. No-op unless
    // .planning/config.json has BOTH graphify.enabled=true AND graphify.auto_update=true.
    const graphifyUpdateCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-graphify-update.sh', hookOpts)
      : localShellCmd('gsd-graphify-update.sh');
    const hasGraphifyUpdateHook = settings.hooks[postToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-graphify-update'))
    );
    const graphifyUpdateFile = path.join(targetDir, 'hooks', 'gsd-graphify-update.sh');
    if (!hasGraphifyUpdateHook && fs.existsSync(graphifyUpdateFile) && graphifyUpdateCommand) {
      settings.hooks[postToolEvent].push({
        matcher: 'Bash',
        hooks: [
          {
            type: 'command',
            command: graphifyUpdateCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured graphify auto-update hook (opt-in via graphify.auto_update)`);
    } else if (!hasGraphifyUpdateHook && !fs.existsSync(graphifyUpdateFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped graphify auto-update hook — gsd-graphify-update.sh not found at target`);
    } else if (!hasGraphifyUpdateHook && !graphifyUpdateCommand) {
      console.warn(`  ${yellow}⚠${reset}  Skipped graphify auto-update hook — Bash executable path unavailable (#3393)`);
    }

    // Configure session state orientation hook (opt-in)
    const sessionStateCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-session-state.sh', hookOpts)
      : localShellCmd('gsd-session-state.sh');
    const hasSessionStateHook = settings.hooks.SessionStart.some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-session-state'))
    );
    const sessionStateFile = path.join(targetDir, 'hooks', 'gsd-session-state.sh');
    if (!hasSessionStateHook && fs.existsSync(sessionStateFile) && sessionStateCommand) {
      settings.hooks.SessionStart.push({
        hooks: [
          {
            type: 'command',
            command: sessionStateCommand
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured session state orientation hook (opt-in via config)`);
    } else if (!hasSessionStateHook && !fs.existsSync(sessionStateFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped session state hook — gsd-session-state.sh not found at target`);
    } else if (!hasSessionStateHook && !sessionStateCommand) {
      console.warn(`  ${yellow}⚠${reset}  Skipped session state hook — Bash executable path unavailable (#3393)`);
    }

    // Configure phase boundary detection hook (opt-in)
    const phaseBoundaryCommand = isGlobal
      ? buildHookCommand(targetDir, 'gsd-phase-boundary.sh', hookOpts)
      : localShellCmd('gsd-phase-boundary.sh');
    const hasPhaseBoundaryHook = settings.hooks[postToolEvent].some(entry =>
      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-phase-boundary'))
    );
    const phaseBoundaryFile = path.join(targetDir, 'hooks', 'gsd-phase-boundary.sh');
    if (!hasPhaseBoundaryHook && fs.existsSync(phaseBoundaryFile) && phaseBoundaryCommand) {
      settings.hooks[postToolEvent].push({
        matcher: 'Write|Edit',
        hooks: [
          {
            type: 'command',
            command: phaseBoundaryCommand,
            timeout: 5
          }
        ]
      });
      console.log(`  ${green}✓${reset} Configured phase boundary detection hook (opt-in via config)`);
    } else if (!hasPhaseBoundaryHook && !fs.existsSync(phaseBoundaryFile)) {
      console.warn(`  ${yellow}⚠${reset}  Skipped phase boundary hook — gsd-phase-boundary.sh not found at target`);
    } else if (!hasPhaseBoundaryHook && !phaseBoundaryCommand) {
      console.warn(`  ${yellow}⚠${reset}  Skipped phase boundary hook — Bash executable path unavailable (#3393)`);
    }

    // ── Extended hook events: SubagentStop / Stop / PreCompact (#788 + #770) ──
    // Claude Code (since #770) and Qwen Code (since #788) both support these
    // three lifecycle events.  Wire gsd-context-monitor so agents get context-
    // headroom warnings at subagent completion, model stop, and pre-compaction
    // (the most critical moment to surface headroom info).
    //
    //   SubagentStop  — subagent lifecycle completion (context headroom tracking)
    //   Stop          — model stop / final-response moment (context headroom)
    //   PreCompact    — fires before conversation compaction (most critical
    //                   moment to surface context headroom warnings)
    //
    // Note: UserPromptSubmit is NOT wired here.  That event carries the raw
    // user prompt text, not a tool invocation, so gsd-prompt-guard (which
    // exits unless tool_name is Write/Edit) would be a silent no-op.  A
    // dedicated handler for UserPromptSubmit is deferred to a follow-on issue.
    if (isQwen || runtime === 'claude') {
      const runtimeLabel = isQwen ? 'Qwen Code' : 'Claude Code';
      // SubagentStop, Stop, PreCompact — route through the context monitor.
      for (const event of ['SubagentStop', 'Stop', 'PreCompact']) {
        if (!settings.hooks[event]) {
          settings.hooks[event] = [];
        }
        const alreadyHasContextMonitor = settings.hooks[event].some(entry =>
          entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-context-monitor'))
        );
        if (!alreadyHasContextMonitor && fs.existsSync(contextMonitorFile) && contextMonitorCommand) {
          settings.hooks[event].push({
            hooks: [
              {
                type: 'command',
                command: contextMonitorCommand,
                timeout: 10
              }
            ]
          });
          console.log(`  ${green}✓${reset} Configured ${event} context monitor hook (${runtimeLabel})`);
        } else if (!alreadyHasContextMonitor && !fs.existsSync(contextMonitorFile)) {
          console.warn(`  ${yellow}⚠${reset}  Skipped ${event} hook — gsd-context-monitor.js not found at target`);
        }
      }
    }
    // ── end SubagentStop / Stop / PreCompact events ────────────────────────────

    // ── Gemini-only extended hook events (#776) ───────────────────────────────
    // Gemini CLI exposes several hook events beyond BeforeTool/AfterTool that
    // gsd previously did not register.  Three high-value events are added here:
    //
    //   BeforeAgent  — fires after user submits a prompt, before the agent
    //                  plans.  Wire gsd-context-monitor for context headroom
    //                  awareness at prompt time.
    //   AfterAgent   — fires once per turn after the model generates its final
    //                  response.  Wire gsd-context-monitor to track headroom
    //                  after each agent turn completes.
    //   BeforeModel  — fires before each LLM call (per-turn, not per-session).
    //                  Wire gsd-context-monitor for per-turn context injection
    //                  — more precise than session-start-only injection.
    //
    // All three reuse gsd-context-monitor.js — no new hook files needed.
    // The `decision:"deny"` retry capability of AfterAgent is intentionally
    // left to the hook script to implement when triggered (gsd-context-monitor
    // exits 0 / advisory-only today; an active quality gate is a follow-on).
    //
    // Note: BeforeToolSelection is NOT wired.  That event does not map to a
    // gsd hook use case at this time; deferred to a follow-on issue.
    //
    // Guard: isGemini is defined at the top of install() (line ~8696).
    if (isGemini) {
      for (const geminiEvent of ['BeforeAgent', 'AfterAgent', 'BeforeModel']) {
        if (!Array.isArray(settings.hooks[geminiEvent])) {
          settings.hooks[geminiEvent] = [];
        }
        const alreadyHasContextMonitor = settings.hooks[geminiEvent].some(entry =>
          entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-context-monitor'))
        );
        if (!alreadyHasContextMonitor && fs.existsSync(contextMonitorFile) && contextMonitorCommand) {
          settings.hooks[geminiEvent].push({
            hooks: [
              {
                type: 'command',
                command: contextMonitorCommand,
                timeout: 10
              }
            ]
          });
          console.log(`  ${green}✓${reset} Configured ${geminiEvent} context monitor hook (Gemini)`);
        } else if (!alreadyHasContextMonitor && !fs.existsSync(contextMonitorFile)) {
          console.warn(`  ${yellow}⚠${reset}  Skipped ${geminiEvent} hook — gsd-context-monitor.js not found at target`);
        }
      }
    }
    // ── end Gemini-only extended hook events ──────────────────────────────────

    // ── FileChanged hook: hot-reload gsd config on .planning/config.json edits ─
    // Claude Code fires FileChanged when a watched file changes on disk.  Wire
    // gsd-config-reload.js to reload the gsd config context whenever the user
    // edits .planning/config.json mid-session, eliminating the need to restart.
    //
    // The matcher "config.json" watches for changes to any file named config.json
    // (Claude Code matches by filename, not full path).  The hook exits silently
    // when the changed file is not the gsd config.
    //
    // Scoped to Claude Code only: Qwen Code's FileChanged support is not yet
    // verified; extend in a follow-on if empirically confirmed.
    if (runtime === 'claude') {
      if (!settings.hooks.FileChanged) {
        settings.hooks.FileChanged = [];
      }
      const configReloadFile = path.join(targetDir, 'hooks', 'gsd-config-reload.js');
      const alreadyHasConfigReload = settings.hooks.FileChanged.some(entry =>
        entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-config-reload'))
      );
      if (!alreadyHasConfigReload && fs.existsSync(configReloadFile) && configReloadCommand) {
        settings.hooks.FileChanged.push({
          matcher: 'config.json',
          hooks: [
            {
              type: 'command',
              command: configReloadCommand,
              timeout: 8
            }
          ]
        });
        console.log(`  ${green}✓${reset} Configured FileChanged config-reload hook (Claude Code)`);
      } else if (!alreadyHasConfigReload && !fs.existsSync(configReloadFile)) {
        console.warn(`  ${yellow}⚠${reset}  Skipped FileChanged hook — gsd-config-reload.js not found at target`);
      } else if (!alreadyHasConfigReload && !configReloadCommand) {
        console.warn(`  ${yellow}⚠${reset}  Skipped FileChanged hook — Node executable path unavailable`);
      }
    }
    // ── end FileChanged hook ────────────────────────────────────────────────────
  }

  // ── Gemini hooksConfig.enabled check (#776) ───────────────────────────────
  // Detect `hooksConfig.enabled: false` in the already-loaded settings object
  // and emit a clear warning.  When this field is false the Gemini CLI silently
  // disables ALL hook execution — gsd hooks are registered but will never run.
  // The check is read-only (warning only; we do not mutate hooksConfig).
  // Note: we use the in-memory `settings` object (already read from disk and
  // cleaned up by validateHookFields/cleanupOrphanedHooks above) rather than
  // re-reading settings.json, avoiding a TOCTOU window between the two reads.
  if (isGemini && settings && settings.hooksConfig && settings.hooksConfig.enabled === false) {
    console.warn(
      `  ${yellow}⚠${reset}  Warning: hooksConfig.enabled is false in your Gemini settings.json.\n` +
      `     gsd-core hooks are registered but will NOT run until you set\n` +
      `     hooksConfig.enabled: true in ${path.join(targetDir, 'settings.json')}.`
    );
  }
  // ── end hooksConfig.enabled check ────────────────────────────────────────

  // Compute the update-banner hook command alongside the others so
  // installAllRuntimes can register it at finalize time when the user opts
  // in (#2795). Computed here (not in finishInstall) so the same buildHookCommand
  // / localCmd resolution logic is shared with the other JS hooks.
  const updateBannerCommand = isOpencode || isKilo
    ? null
    : (isGlobal
      ? buildHookCommand(targetDir, 'gsd-update-banner.js', hookOpts)
      : localCmd('gsd-update-banner.js'));

  // #683: Set worktree.baseRef:"head" in settings.local.json for local Claude installs.
  // Both fresh and upgrade paths apply only when worktrees are enabled for the project.
  // Never applies to global installs, non-Claude runtimes, or when the user already
  // has an explicit baseRef in EITHER settings.local.json OR settings.json (no-clobber).
  // Guard: skip entirely when settings is not a plain object (e.g. parsed to [] or primitive)
  // to avoid crashing applyWorktreeBaseRef on unexpected top-level shapes.
  if (isLocalClaude && settings !== null && typeof settings === 'object' && !Array.isArray(settings)) {
    // Read shared settings.json baseRef so no-clobber spans both files (#683 FIX 1).
    // shared settings.json no-clobber is checked here; settings.local.json no-clobber
    // is enforced inside applyWorktreeBaseRef itself.
    const sharedSettingsForBaseRef = readSettings(path.join(targetDir, 'settings.json')) || {};
    const sharedBaseRef = readBaseRefFromSettings(sharedSettingsForBaseRef);

    // Compute worktrees-enabled ONCE for both fresh and upgrade paths (FIX A: DRY + consistency).
    // Read workflow.use_worktrees from .planning/config.json by walking up from
    // targetDir (same walk-up pattern as readGsdRuntimeProfileResolver). Defaults
    // to enabled (true) when the file is missing, unreadable, or the key is absent;
    // only boolean false disables (string "false" stays enabled).
    let worktreesEnabled = true; // default: enabled
    try {
      let probeDir = path.resolve(targetDir);
      for (let depth = 0; depth < 8; depth += 1) {
        const candidate = path.join(probeDir, '.planning', 'config.json');
        if (fs.existsSync(candidate)) {
          try {
            const parsed = JSON.parse(stripJsonComments(fs.readFileSync(candidate, 'utf-8')));
            if (parsed && typeof parsed === 'object' &&
                parsed.workflow && parsed.workflow.use_worktrees === false) {
              worktreesEnabled = false;
            }
          } catch {
            // Malformed config.json — treat as enabled (safe fallback).
          }
          break;
        }
        const parent = path.dirname(probeDir);
        if (parent === probeDir) break;
        probeDir = parent;
      }
    } catch {
      // Any unexpected error reading .planning — default to enabled.
    }

    if (worktreesEnabled && sharedBaseRef === null) {
      if (!priorInstallExisted) {
        // Fresh install — apply no-clobber baseRef set.
        // canonical no-clobber logic: src/worktree-base-ref.cts applyWorktreeBaseRef (#683)
        const { changed } = applyWorktreeBaseRef(settings);
        if (changed) {
          console.log(`  ${green}✓${reset} Set worktree.baseRef:"head" for Claude Code worktrees (forks phase worktrees off HEAD; #683)`);
        }
      } else {
        // Upgrade — auto-apply no-clobber baseRef set when worktrees are enabled.
        const { changed } = applyWorktreeBaseRef(settings);
        if (changed) {
          console.log(`  ${green}✓${reset} Enabled worktree.baseRef:"head" for Claude Code worktrees (forks phase worktrees off HEAD; #683)`);
        }
      }
    }
    // When worktreesEnabled is false: do nothing, print nothing (both fresh and upgrade).
  }

  persistActiveProfileMarker();
  return {
    settingsPath,
    settings,
    statuslineCommand,
    updateBannerCommand,
    runtime,
    configDir: targetDir,
    rollbackInstallerMigrations,
  };
}

/**
 * Apply statusline config, then print completion message
 */
function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true, configDir = null, bannerOpts = {}) {
  const isOpencode = runtime === 'opencode';
  const isKilo = runtime === 'kilo';
  const isCodex = runtime === 'codex';
  const isCopilot = runtime === 'copilot';
  const isCursor = runtime === 'cursor';
  const isWindsurf = runtime === 'windsurf';
  const isTrae = runtime === 'trae';
  const isCline = runtime === 'cline';
  const configIntent = resolveRuntimeConfigIntent(runtime);

  if (shouldInstallStatusline && configIntent.writesSharedSettings && !isOpencode) {
    if (!isGlobal && !forceStatusline) {
      // Local installs skip statusLine by default: repo settings.json takes precedence over
      // profile-level settings.json in Claude Code, so writing here would silently clobber
      // any profile-level statusLine the user has configured (#2248).
      // Pass --force-statusline to override this guard.
      console.log(`  ${yellow}⚠${reset} Skipping statusLine for local install (avoids overriding profile-level settings; use --force-statusline to override)`);
    } else if (!statuslineCommand) {
      // #3002 CR: don't write { type: 'command', command: null } — the
      // runtime's settings schema rejects null commands and the failure
      // surfaces as a confusing parse error rather than a usable diagnostic.
      console.warn(`  ${yellow}⚠${reset}  Skipped statusline registration — Node executable path unavailable (process.execPath is empty). See #2979 / #3002.`);
    } else {
      settings.statusLine = {
        type: 'command',
        command: statuslineCommand
      };
      console.log(`  ${green}✓${reset} Configured statusline`);
    }
  }

  // Register the opt-in update banner (#2795) when the user accepted the
  // banner offer at install time. Only applies to runtimes that own a
  // settings.json hooks block — opencode/kilo/codex/cursor/windsurf/trae/
  // cline either lack the surface or use a different config schema.
  const { shouldInstallBanner, bannerCommand } = bannerOpts;
  if (shouldInstallBanner && settings && configIntent.writesSharedSettings && !isOpencode) {
    if (!bannerCommand) {
      console.warn(`  ${yellow}⚠${reset}  Skipped update banner registration — Node executable path unavailable. See #2979 / #3002.`);
    } else {
      if (!settings.hooks) settings.hooks = {};
      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
      const alreadyRegistered = settings.hooks.SessionStart.some(entry =>
        entry && entry.hooks && entry.hooks.some(h => h && h.command && h.command.includes('gsd-update-banner'))
      );
      const bannerHookFile = configDir ? path.join(configDir, 'hooks', 'gsd-update-banner.js') : null;
      const bannerInstalled = bannerHookFile ? fs.existsSync(bannerHookFile) : false;
      if (alreadyRegistered) {
        // Idempotent re-install: don't double-register.
      } else if (!bannerInstalled) {
        console.warn(`  ${yellow}⚠${reset}  Skipped update banner — gsd-update-banner.js not found at target`);
      } else {
        const entry = buildUpdateBannerHookEntry(bannerCommand);
        if (entry) {
          settings.hooks.SessionStart.push(entry);
          console.log(`  ${green}✓${reset} Configured update banner hook (opt-in)`);
        }
      }
    }
  }

  // #768 — Pre-populate permissions.allow/deny for Claude Code installs.
  // Merges GSD-owned entries non-destructively (preserves existing user permissions).
  // Scoped to Claude only: gemini/antigravity/qwen/hermes/codebuddy also write
  // settings.json but use different runtimes and do not use these permission strings.
  if (runtime === 'claude') {
    mergeClaudePermissions(settings);
  }

  // Write settings when runtime supports settings.json.
  // #3002 CR: defense-in-depth — re-run validateHookFields right before
  // serialization. The push-site guards above already skip null-command
  // entries, but a future regression that bypasses them would still produce
  // {type: 'command', command: null} items that the runtime hook schema
  // rejects at parse time. validateHookFields filters those out so the file
  // we write is always schema-valid.
  if (settingsPath && settings && configIntent.writesSharedSettings) {
    writeSettings(settingsPath, validateHookFields(settings));
  }

  // Configure OpenCode permissions
  if (configIntent.finishPermissionWriter === 'opencode' && !process.env.GSD_TEST_MODE) {
    configureOpencodePermissions(isGlobal, configDir);
  }

  // Configure Kilo permissions
  if (configIntent.finishPermissionWriter === 'kilo') {
    configureKiloPermissions(isGlobal, configDir);
  }

  // For non-Claude runtimes, set resolve_model_ids: "omit" in ~/.gsd/defaults.json
  // so resolveModelInternal() returns '' instead of Claude aliases (opus/sonnet/haiku)
  // that the runtime can't resolve. Users can still use model_overrides for explicit IDs.
  // See #1156. Guard matches the #130-class pattern on configureOpencodePermissions above.
  if (runtime !== 'claude' && !process.env.GSD_TEST_MODE) {
    const gsdDir = path.join(os.homedir(), '.gsd');
    const defaultsPath = path.join(gsdDir, 'defaults.json');
    try {
      fs.mkdirSync(gsdDir, { recursive: true });
      let defaults = {};
      try { defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')); } catch { /* new file */ }
      if (defaults.resolve_model_ids !== 'omit') {
        defaults.resolve_model_ids = 'omit';
        fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
        console.log(`  ${green}✓${reset} Set resolve_model_ids: "omit" in ~/.gsd/defaults.json`);
      }
    } catch (e) {
      console.log(`  ${yellow}⚠${reset} Could not write ~/.gsd/defaults.json: ${e.message}`);
    }
  }

  let program = 'Claude Code';
  if (runtime === 'opencode') program = 'OpenCode';
  if (runtime === 'gemini') program = 'Gemini';
  if (runtime === 'kilo') program = 'Kilo';
  if (runtime === 'codex') program = 'Codex';
  if (runtime === 'copilot') program = 'Copilot';
  if (runtime === 'antigravity') program = 'Antigravity';
  if (runtime === 'cursor') program = 'Cursor';
  if (runtime === 'windsurf') program = 'Windsurf';
  if (runtime === 'augment') program = 'Augment';
  if (runtime === 'trae') program = 'Trae';
  if (runtime === 'cline') program = 'Cline';
  if (runtime === 'qwen') program = 'Qwen Code';
  if (runtime === 'hermes') program = 'Hermes Agent';
  if (runtime === 'kimi') program = 'Kimi CLI';

  let command = '/gsd-new-project';
  if (runtime === 'opencode') command = '/gsd-new-project';
  if (runtime === 'kilo') command = '/gsd-new-project';
  if (runtime === 'gemini') command = '/gsd:new-project';
  if (runtime === 'codex') command = '$gsd-new-project';
  if (runtime === 'copilot') command = '/gsd-new-project';
  if (runtime === 'antigravity') command = '/gsd-new-project';
  if (runtime === 'cursor') command = 'gsd-new-project (mention the skill name)';
  if (runtime === 'windsurf') command = '/gsd-new-project';
  if (runtime === 'augment') command = '/gsd-new-project';
  if (runtime === 'trae') command = '/gsd-new-project';
  if (runtime === 'cline') command = '/gsd-new-project';
  if (runtime === 'qwen') command = '/gsd-new-project';
  if (runtime === 'hermes') command = '/gsd-new-project';
  if (runtime === 'kimi') command = '/skill:gsd-new-project';

  // Claude Code global installs use the skills/ format (CC 2.1.88+).
  // Restart is required for CC to pick up newly-installed skills, and the
  // slash-menu surface depends on CC version — so the instruction needs to
  // cover both invocation paths to avoid #2957-style "no commands appear".
  if (runtime === 'claude' && isGlobal) {
    console.log(`
  ${green}Done!${reset} Restart ${program}, then in any directory either type ${cyan}${command}${reset} or ask Claude to run the ${cyan}gsd-new-project${reset} skill.

  ${cyan}Join the community:${reset} https://discord.gg/mYgfVNfA2r
`);
    return;
  }

  if (runtime === 'kimi') {
    const agentPath = configDir ? path.join(configDir, 'agents', 'gsd.yaml') : 'agents/gsd.yaml';
    console.log(`
  ${green}Done!${reset} Start ${program} with ${cyan}kimi --agent-file ${agentPath}${reset}, then run ${cyan}${command}${reset}.

  ${cyan}Join the community:${reset} https://discord.gg/mYgfVNfA2r
`);
    return;
  }

  console.log(`
  ${green}Done!${reset} Open a blank directory in ${program} and run ${cyan}${command}${reset}.

  ${cyan}Join the community:${reset} https://discord.gg/mYgfVNfA2r
`);
}

/**
 * Handle statusline configuration with optional prompt
 */
function handleStatusline(settings, isInteractive, callback) {
  const hasExisting = settings.statusLine != null;

  if (!hasExisting) {
    callback(true);
    return;
  }

  if (forceStatusline) {
    callback(true);
    return;
  }

  if (!isInteractive) {
    console.log(`  ${yellow}⚠${reset} Skipping statusline (already configured)`);
    console.log(`    Use ${cyan}--force-statusline${reset} to replace\n`);
    callback(false);
    return;
  }

  const existingCmd = settings.statusLine.command || settings.statusLine.url || '(custom)';

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });

  console.log(`
  ${yellow}⚠${reset} Existing statusline detected\n
  Your current statusline:
    ${dim}command: ${existingCmd}${reset}

  GSD includes a statusline showing:
    • Model name
    • Current task (from todo list)
    • Context window usage (color-coded)

  ${cyan}1${reset}) Keep existing
  ${cyan}2${reset}) Replace with GSD statusline
`);

  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
    rl.close();
    const choice = answer.trim() || '1';
    callback(choice === '2');
  });
}

/**
 * Prompt for runtime selection
 */
/**
 * Runtime selection options for the interactive installer prompt.
 * Module-level so tests can import and assert structurally without grepping source.
 */
const runtimeMap = {
  '1': 'claude',
  '2': 'antigravity',
  '3': 'augment',
  '4': 'cline',
  '5': 'codebuddy',
  '6': 'codex',
  '7': 'copilot',
  '8': 'cursor',
  '9': 'gemini',
  '10': 'hermes',
  '11': 'kimi',
  '12': 'kilo',
  '13': 'opencode',
  '14': 'qwen',
  '15': 'trae',
  '16': 'windsurf'
};
const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'gemini', 'hermes', 'kimi', 'kilo', 'opencode', 'qwen', 'trae', 'windsurf'];
const ALL_RUNTIMES_OPTION = '17';

/**
 * Build the runtime-selection prompt text shown by the interactive installer.
 * Pure function — no I/O. Exported for tests so they can assert against the
 * rendered prompt instead of grepping bin/install.js source text.
 */
function buildRuntimePromptText() {
  return `  ${yellow}Which runtime(s) would you like to install for?${reset}\n\n  ${cyan}1${reset}) Claude Code  ${dim}(~/.claude)${reset}
  ${cyan}2${reset}) Antigravity  ${dim}(~/.gemini/antigravity)${reset}
  ${cyan}3${reset}) Augment      ${dim}(~/.augment)${reset}
  ${cyan}4${reset}) Cline        ${dim}(.clinerules)${reset}
  ${cyan}5${reset}) CodeBuddy    ${dim}(~/.codebuddy)${reset}
  ${cyan}6${reset}) Codex        ${dim}(~/.codex)${reset}
  ${cyan}7${reset}) Copilot      ${dim}(~/.copilot)${reset}
  ${cyan}8${reset}) Cursor       ${dim}(~/.cursor)${reset}
  ${cyan}9${reset}) Gemini       ${dim}(~/.gemini)${reset}
  ${cyan}10${reset}) Hermes Agent ${dim}(~/.hermes)${reset}
  ${cyan}11${reset}) Kimi         ${dim}(~/.config/agents, then ~/.agents if existing)${reset}
  ${cyan}12${reset}) Kilo         ${dim}(~/.config/kilo)${reset}
  ${cyan}13${reset}) OpenCode     ${dim}(~/.config/opencode)${reset}
  ${cyan}14${reset}) Qwen Code    ${dim}(~/.qwen)${reset}
  ${cyan}15${reset}) Trae         ${dim}(~/.trae)${reset}
  ${cyan}16${reset}) Windsurf     ${dim}(~/.codeium/windsurf)${reset}
  ${cyan}17${reset}) All

  ${dim}Select multiple: 1,2,6 or 1 2 6${reset}
`;
}

/**
 * Parse user input from the runtime-selection prompt into a runtime list.
 * Pure function — exported so tests can verify split/dedupe/fallback behavior.
 *  - Accepts comma- and/or whitespace-separated choices
 *  - Deduplicates while preserving order
 *  - Maps option 17 ("All") to every runtime
 *  - Falls back to ['claude'] when nothing valid is selected
 */
function parseRuntimeInput(answer) {
  const input = (answer == null ? '' : String(answer)).trim() || '1';

  // Tokenize first so the all-runtimes shortcut also fires for inputs the
  // prompt encourages — "16,", "16 1", etc. — not just the bare "16".
  const choices = input.split(/[\s,]+/).filter(Boolean);
  if (choices.includes(ALL_RUNTIMES_OPTION)) {
    return allRuntimes.slice();
  }

  const selected = [];
  for (const c of choices) {
    const runtime = runtimeMap[c];
    if (runtime && !selected.includes(runtime)) {
      selected.push(runtime);
    }
  }

  return selected.length > 0 ? selected : ['claude'];
}

function promptRuntime(callback) {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });

  let answered = false;

  rl.on('close', () => {
    if (!answered) {
      answered = true;
      console.log(`\n  ${yellow}Installation cancelled${reset}\n`);
      process.exit(0);
    }
  });

  console.log(buildRuntimePromptText());

  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
    answered = true;
    rl.close();
    callback(parseRuntimeInput(answer));
  });
}

// ─── Update banner (#2795) ──────────────────────────────────────────────────

/**
 * Build the prompt text shown when offering the opt-in update banner.
 * Pure function — no I/O. Exported for tests so they can assert against the
 * rendered prompt structurally instead of grepping bin/install.js source.
 */
function buildUpdateBannerPromptText() {
  return `
  ${yellow}Optional: GSD update banner${reset}
  Without GSD's statusline, update notifications won't be visible. You can
  install a SessionStart banner that surfaces a one-line message when a new
  GSD release is available. The banner appears only at session start and
  only when an update exists.

  ${cyan}1${reset}) ${dim}No banner (default)${reset}
  ${cyan}2${reset}) Install update banner
`;
}

/**
 * Parse user input from the banner prompt. Returns true when the user opted
 * in. Pure function — exported for direct unit testing.
 *
 *  - Empty input or "1" → false (default: no banner).
 *  - "2" → true.
 *  - "y" / "yes" (case-insensitive) → true. Affirmative shortcuts.
 */
function parseUpdateBannerInput(answer) {
  const input = (answer == null ? '' : String(answer)).trim().toLowerCase();
  if (input === '2' || input === 'y' || input === 'yes') return true;
  return false;
}

/**
 * Build a SessionStart hook entry (settings.json shape) that runs the
 * update-banner script. Returns null when the input command is empty so
 * callers can warn-and-skip rather than writing { command: null } and
 * tripping the runtime's hook schema (#3002).
 *
 * @param {string|null} bannerCommand - Result of buildHookCommand() / localCmd().
 * @returns {{hooks: Array<{type: 'command', command: string}>}|null}
 */
function buildUpdateBannerHookEntry(bannerCommand) {
  if (!bannerCommand) return null;
  return {
    hooks: [
      {
        type: 'command',
        command: bannerCommand,
      },
    ],
  };
}

/**
 * Interactive prompt that asks the user whether to install the opt-in
 * update banner. Used by `installAllRuntimes` only when GSD's statusline
 * was declined or skipped.
 *
 * @param {boolean} isInteractive
 * @param {(shouldInstallBanner: boolean) => void} callback
 */
function handleUpdateBanner(isInteractive, callback) {
  if (!isInteractive) {
    // Never auto-install in non-interactive mode — user can re-run install
    // interactively or hand-edit settings.json to opt in later.
    callback(false);
    return;
  }

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  console.log(buildUpdateBannerPromptText());

  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
    rl.close();
    callback(parseUpdateBannerInput(answer));
  });
}

/**
 * Prompt for install location
 */
function promptLocation(runtimes) {
  if (!process.stdin.isTTY) {
    console.log(`  ${yellow}Non-interactive terminal detected, defaulting to global install${reset}\n`);
    installAllRuntimes(runtimes, true, false);
    return;
  }

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });

  let answered = false;

  rl.on('close', () => {
    if (!answered) {
      answered = true;
      console.log(`\n  ${yellow}Installation cancelled${reset}\n`);
      process.exit(0);
    }
  });

  const pathExamples = runtimes.map(r => {
    const globalPath = getGlobalConfigDir(r, explicitConfigDir);
    return globalPath.replace(os.homedir(), '~');
  }).join(', ');

  const localExamples = runtimes.map(r => `./${getDirName(r)}`).join(', ');

  console.log(`  ${yellow}Where would you like to install?${reset}\n\n  ${cyan}1${reset}) Global ${dim}(${pathExamples})${reset} - available in all projects
  ${cyan}2${reset}) Local  ${dim}(${localExamples})${reset} - this project only
`);

  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
    answered = true;
    rl.close();
    const choice = answer.trim() || '1';
    const isGlobal = choice !== '2';
    installAllRuntimes(runtimes, isGlobal, true);
  });
}

/**
 * Check whether any common shell rc file already contains a `PATH=` line
 * whose HOME-expanded value places `globalBin` on PATH (#2620).
 *
 * Parses `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.profile` (or the
 * override list in `rcFileNames`), matches `export PATH=` / bare `PATH=`
 * lines, and substitutes the common HOME forms (`$HOME`, `${HOME}`, `~`)
 * with `homeDir` before comparing each PATH segment against `globalBin`.
 *
 * Best-effort: any unreadable / malformed / non-existent rc file is ignored
 * and the fallback is the caller's existing absolute-path suggestion. Only
 * the `$HOME/…`, `${HOME}/…`, and `~/…` forms are handled — we do not try
 * to fully parse bash syntax.
 *
 * @param {string} globalBin  Absolute path to npm's global bin directory.
 * @param {string} homeDir    Absolute path used to substitute HOME / ~.
 * @param {string[]} [rcFileNames]  Override the default rc file list.
 * @returns {boolean}         true iff any rc file adds globalBin to PATH.
 */
function homePathCoveredByRc(globalBin, homeDir, rcFileNames) {
  if (!globalBin || !homeDir) return false;
  const path = require('path');
  const fs = require('fs');

  const normalise = (p) => {
    if (!p) return '';
    let n = p.replace(/[\\/]+$/g, '');
    if (n === '') n = p.startsWith('/') ? '/' : p;
    return n;
  };

  const targetAbs = normalise(path.resolve(globalBin));
  const homeAbs = path.resolve(homeDir);
  const files = rcFileNames || ['.zshrc', '.bashrc', '.bash_profile', '.profile'];

  const expandHome = (segment) => {
    let s = segment;
    s = s.replace(/\$\{HOME\}/g, homeAbs);
    s = s.replace(/\$HOME/g, homeAbs);
    if (s.startsWith('~/') || s === '~') {
      s = s === '~' ? homeAbs : path.join(homeAbs, s.slice(2));
    }
    return s;
  };

  // Match `PATH=…` (optionally prefixed with `export `). The RHS captures
  // through end-of-line; surrounding quotes are stripped before splitting.
  const assignRe = /^\s*(?:export\s+)?PATH\s*=\s*(.+?)\s*$/;

  for (const name of files) {
    const rcPath = path.join(homeAbs, name);
    let content;
    try {
      content = fs.readFileSync(rcPath, 'utf8');
    } catch {
      continue;
    }

    for (const rawLine of content.split(/\r?\n/)) {
      const line = rawLine.replace(/^\s+/, '');
      if (line.startsWith('#')) continue;

      const m = assignRe.exec(rawLine);
      if (!m) continue;

      let rhs = m[1];
      if ((rhs.startsWith('"') && rhs.endsWith('"')) ||
          (rhs.startsWith("'") && rhs.endsWith("'"))) {
        rhs = rhs.slice(1, -1);
      }

      for (const segment of rhs.split(':')) {
        if (!segment) continue;
        const trimmed = segment.trim();
        const expanded = expandHome(trimmed);
        if (expanded.includes('$')) continue;
        // Skip segments that are still relative after HOME expansion. A bare
        // `bin` entry (or `./bin`, `node_modules/.bin`, etc.) depends on the
        // shell's cwd at lookup time — it is NOT equivalent to `$HOME/bin`,
        // so resolving against homeAbs would produce false positives.
        if (!path.isAbsolute(expanded)) continue;
        try {
          const abs = normalise(path.resolve(expanded));
          if (abs === targetAbs) return true;
        } catch {
          // ignore unresolvable segments
        }
      }
    }
  }

  return false;
}

/**
 * Emit a PATH-export suggestion if globalBin is not already on PATH AND
 * the user's shell rc files do not already cover it via a HOME-relative
 * entry (#2620).
 *
 * Prints one of:
 *   - nothing, if `globalBin` is already present on `process.env.PATH`
 *   - a diagnostic "already covered via rc file" note, if an rc file has
 *     `export PATH="$HOME/…/bin:$PATH"` (or equivalent) and the user just
 *     needs to reopen their shell
 *   - projected shell actions that append `export PATH="…:$PATH"` to
 *     `~/.zshrc` / `~/.bashrc` when neither PATH nor rc files cover globalBin
 *     if neither PATH nor any rc file covers globalBin
 *
 * Exported for tests; the installer calls this from finishInstall.
 *
 * @param {string} globalBin  Absolute path to npm's global bin directory.
 * @param {string} homeDir    Absolute HOME path.
 */
function maybeSuggestPathExport(globalBin, homeDir) {
  if (!globalBin || !homeDir) return;
  const path = require('path');

  const pathEnv = process.env.PATH || '';
  const targetAbs = path.resolve(globalBin).replace(/[\\/]+$/g, '') || globalBin;
  const onPath = pathEnv.split(path.delimiter).some((seg) => {
    if (!seg) return false;
    const abs = path.resolve(seg).replace(/[\\/]+$/g, '') || seg;
    return abs === targetAbs;
  });
  if (onPath) return;

  // Already added to PATH via an rc file, but the current shell predates that
  // edit — tell the user to reopen rather than (wrongly) suggesting they add it
  // again. Applies to whatever bin dir we install into (retained shim-agnostic).
  if (homePathCoveredByRc(globalBin, homeDir)) {
    console.log('');
    console.log(`  ${yellow}⚠${reset} ${bold}${globalBin}${reset}'s directory is already on your PATH via an rc file entry — try reopening your shell (or ${cyan}source ~/.zshrc${reset}).`);
    console.log('');
    return;
  }

  console.log('');
  console.log(`  ${yellow}⚠${reset} ${bold}${globalBin}${reset} is not on your PATH.`);
  console.log(`    Add it with one of:`);
  const projected = projectPersistentPathExportActions({
    targetDir: globalBin,
    platform: process.platform,
  });
  for (const action of projected.shellActions) {
    const labelPrefix = action.label ? `${action.label}: ` : '';
    console.log(`      ${cyan}${labelPrefix}${action.command}${reset}`);
  }
  console.log('');
}

// Runtime subdir names to scan for legacy get-shit-done-cc artifacts (#607).
// Covers both local (project-relative) and common global forms.
const _LEGACY_SCAN_SUBDIR_NAMES = [
  '.claude',
  '.gemini',
  '.opencode',
  '.config/opencode',
  '.kilo',
  '.config/kilo',
  '.codex',
  '.copilot',
  '.github',    // copilot local form
  '.agent',     // antigravity local form
  '.cursor',
  '.windsurf',
  '.codeium/windsurf',
  '.augment',
  '.trae',
  '.qwen',
  '.hermes',
  '.codebuddy',
  '.cline',
];

/**
 * Detect and remove leftover get-shit-done-cc artifacts across ALL known
 * runtime config directories (issue #607).
 *
 * Exported so tests can call it directly without spawning a subprocess.
 *
 * Scans ONLY subdirs under homeDir — never cwd — to avoid touching the
 * user's active-project hooks when the installer is run from a project dir.
 *
 * @param {object} [opts]
 * @param {string}  [opts.homeDir=os.homedir()]  - home directory to scan
 * @param {boolean} [opts.dryRun=false]          - preview only; no mutations
 * @param {object}  [opts.logger=console]        - injectable logger
 * @returns {{ plan: {path:string,reason:string}[], result: object }}
 */
function cleanupLegacyGsdCc({ homeDir = os.homedir(), dryRun = false, logger = console } = {}) {
  // Build de-duplicated list of candidate config dirs to scan.
  // Only scan under homeDir — never cwd — to prevent accidental deletion of
  // the user's active-project hooks when the installer is invoked from a
  // project directory that has .claude/hooks or similar subdirs.
  const seen = new Set();
  const configDirs = [];
  for (const name of _LEGACY_SCAN_SUBDIR_NAMES) {
    const candidate = path.join(homeDir, name);
    if (!seen.has(candidate) && fs.existsSync(candidate)) {
      seen.add(candidate);
      configDirs.push(candidate);
    }
  }

  // planLegacyCleanup scans each configDir and already includes the legacy
  // shared cache (gsd-update-check.json) as a plan entry.
  const plan = planLegacyCleanup(configDirs, { homeDir });

  // Apply the plan (dryRun honors the flag).
  const result = applyLegacyCleanup(plan, { dryRun, logger });

  // Also clear / preview the per-package cache so next session re-evaluates
  // hook versions (replaces the former inline unlinkSync on line ~9104).
  const perPkgCacheFile = path.join(homeDir, '.cache', 'gsd', updateCacheFileName);
  if (dryRun) {
    logger.log('[dry-run] would remove: ' + perPkgCacheFile + '  (per-package-update-cache)');
  } else {
    try { fs.unlinkSync(perPkgCacheFile); } catch (_e) { /* cache may not exist yet */ }
  }

  // Concise summary
  if (plan.length > 0 || !dryRun) {
    const verb = dryRun ? 'Would remove' : 'Removed';
    const count = dryRun ? plan.length : result.removed.length;
    logger.log(`[legacy-cleanup] ${verb} ${count} legacy artifact(s).`);
  }

  return { plan, result };
}

/**
 * Install GSD for all selected runtimes
 */
function installAllRuntimes(runtimes, isGlobal, isInteractive) {
  const results = [];
  const installerMigrations = discoverInstallerMigrations({
    migrationsDir: path.join(_gsdLibDir, 'installer-migrations'),
  });

  const rollbackFinalizedInstallerMigrations = (error) => {
    const rollbackFailures = [];
    for (const result of [...results].reverse()) {
      if (!result || typeof result.rollbackInstallerMigrations !== 'function') continue;
      try {
        result.rollbackInstallerMigrations();
      } catch (rollbackError) {
        rollbackFailures.push({
          runtime: result.runtime,
          error: rollbackError.message,
        });
      }
    }
    if (rollbackFailures.length > 0) {
      error.installerMigrationRollbackFailures = rollbackFailures;
    }
  };

  try {
    for (const runtime of runtimes) {
      const result = install(isGlobal, runtime, { installerMigrations });
      results.push(result);
    }
  } catch (error) {
    rollbackFinalizedInstallerMigrations(error);
    throw error;
  }

  const statuslineRuntimes = ['claude', 'gemini'];
  const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));

  const finalize = (shouldInstallStatusline, shouldInstallBanner) => {
    try {
      const printSummaries = () => {
        for (const result of results) {
          if (result && result.skipped) continue;
          if (!result) continue;
          const useStatusline = statuslineRuntimes.includes(result.runtime) && shouldInstallStatusline;
          finishInstall(
            result.settingsPath,
            result.settings,
            result.statuslineCommand,
            useStatusline,
            result.runtime,
            isGlobal,
            result.configDir,
            { shouldInstallBanner: !!shouldInstallBanner, bannerCommand: result.updateBannerCommand }
          );
        }
      };

      printSummaries();
    } catch (error) {
      // Phase 4 install/update integration requires safe migrations to roll
      // back when later package/finalization materialization fails:
      // docs/installer-migrations.md#phase-4-installupdate-integration.
      rollbackFinalizedInstallerMigrations(error);
      throw error;
    }
  };

  // Statusline first; if it won't actually be installed (declined, or local
  // install without --force-statusline silently skips it per #2248), offer
  // the opt-in update banner (#2795) as the secondary surface for update
  // notifications. Skip the banner prompt entirely when no runtime in this
  // install set can host the banner (e.g. Codex/Copilot/Cursor/Windsurf/
  // Trae/Cline-only installs whose updateBannerCommand is null).
  //
  // CR #3035: gate on actual installability — `shouldInstallStatusline`
  // returned by handleStatusline is the raw user choice, but
  // `finishInstall` later skips the statusline write on local installs
  // unless --force-statusline is set. Passing the raw flag to
  // continueAfterStatusline previously caused two bugs: (1) interactive
  // local installs got neither a statusline nor a banner offer, and (2)
  // banner-incapable runtimes got prompted even though every
  // updateBannerCommand was null.
  const canInstallBanner = results.some((r) => r && r.updateBannerCommand);
  const continueAfterStatusline = (shouldInstallStatusline) => {
    const willInstallStatusline =
      shouldInstallStatusline && (isGlobal || forceStatusline);
    if (willInstallStatusline) {
      finalize(true, false);
      return;
    }
    if (!canInstallBanner) {
      finalize(shouldInstallStatusline, false);
      return;
    }
    handleUpdateBanner(isInteractive, (shouldInstallBanner) => {
      finalize(shouldInstallStatusline, shouldInstallBanner);
    });
  };

  if (primaryStatuslineResult) {
    handleStatusline(primaryStatuslineResult.settings, isInteractive, continueAfterStatusline);
  } else if (canInstallBanner) {
    // No statusline-capable runtime, but at least one runtime can host the
    // banner — still offer it.
    handleUpdateBanner(isInteractive, (shouldInstallBanner) => {
      finalize(false, shouldInstallBanner);
    });
  } else {
    // Nothing to prompt about — no statusline, no banner-capable runtime.
    finalize(false, false);
  }
}

// Always export so runtime-artifact-layout.cjs's lazy loader can access
// converter functions when called from within the CLI path (circular require).
// The main() block below is gated on !GSD_TEST_MODE, as before.
module.exports = {
    // #3677 — hyphen-namespace normalization seam for agent bodies
    shouldNormalizeHyphenNamespaceInAgentBody,
    normalizeAgentBodyForRuntime,
    yamlIdentifier,
    computePathPrefix,
    applyRuntimeContentRewritesInPlace,
    getCodexSkillAdapterHeader,
    convertClaudeCommandToCursorSkill,
    convertClaudeCommandToCursorCommand,
    convertClaudeAgentToCursorAgent,
    convertClaudeToGeminiMarkdown,
    convertSlashCommandsToGeminiMentions,
    _resetGsdCommandRoster,
    convertClaudeToGeminiAgent,
    convertClaudeAgentToCodexAgent,
    generateCodexAgentToml,
    generateCodexSkillMetadataYaml,
    writeCodexSkillMetadataFiles,
    generateCodexConfigBlock,
    stripGsdFromCodexConfig,
    migrateCodexHooksMapFormat,
    stripStaleGsdHookBlocks,
    hasUserNamespacedAotHooks,
    parseTomlToObject,
    validateCodexConfigSchema,
    mergeCodexConfig,
    installCodexConfig,
    readGsdRuntimeProfileResolver,
    readGsdEffectiveModelOverrides,
    readGsdEffectiveEffortConfig,
    resolveInstallTimeEffort,
    injectEffortFrontmatter,
    get _GSD_EFFORT_MANIFEST_TIER_DEFAULTS() { return _getGsdEffortCatalog().EFFORT_MANIFEST_TIER_DEFAULTS; },
    get _GSD_EFFORT_MANIFEST_DEFAULT() { return _getGsdEffortCatalog().EFFORT_MANIFEST_DEFAULT; },
    install,
    installAllRuntimes,
    uninstall,
    convertSlashCommandsToCodexSkillMentions,
    convertClaudeCommandToCodexSkill,
    convertClaudeCommandToKimiSkill,
    convertKimiToolName,
    mapClaudeToolsToKimiTools,
    buildKimiAgentArtifacts,
    convertClaudeToOpencodeFrontmatter,
    convertClaudeToKiloFrontmatter,
    convertClaudeCommandToOpencodeSkill,
    convertClaudeCommandToKiloSkill,
    configureOpencodePermissions,
    neutralizeAgentReferences,
    // #768 — Claude Code permissions pre-population
    mergeClaudePermissions,
    GSD_CLAUDE_ALLOW_PERMISSIONS,
    GSD_CLAUDE_DENY_PERMISSIONS,
    GSD_CODEX_MARKER,
    CODEX_AGENT_SANDBOX,
    getDirName,
    getGlobalDir,
    getConfigDirFromHome,
    resolveKiloConfigPath,
    configureKiloPermissions,
    claudeToCopilotTools,
    convertCopilotToolName,
    convertClaudeToCopilotContent,
    convertClaudeCommandToCopilotSkill,
    convertClaudeAgentToCopilotAgent,
    GSD_COPILOT_INSTRUCTIONS_MARKER,
    GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER,
    mergeCopilotInstructions,
    stripGsdFromCopilotInstructions,
    GSD_COPILOT_HOOK_FILE,
    buildCopilotHookConfig,
    writeCopilotHookConfig,
    convertClaudeToAntigravityContent,
    convertClaudeCommandToAntigravitySkill,
    convertClaudeAgentToAntigravityAgent,
    convertClaudeCommandToClaudeSkill,
    skillFrontmatterName,
    convertClaudeToWindsurfMarkdown,
    convertClaudeCommandToWindsurfSkill,
    convertClaudeAgentToWindsurfAgent,
    convertClaudeToAugmentMarkdown,
    convertClaudeCommandToAugmentSkill,
    convertClaudeAgentToAugmentAgent,
    convertClaudeToTraeMarkdown,
    convertClaudeCommandToTraeSkill,
    convertClaudeAgentToTraeAgent,
    convertClaudeToCodebuddyMarkdown,
    convertClaudeCommandToCodebuddySkill,
    convertClaudeCommandToCodebuddyCommand,
    convertClaudeAgentToCodebuddyAgent,
    convertClaudeToCliineMarkdown,
    convertClaudeCommandToClineSkill,
    convertClaudeAgentToClineAgent,
    buildClineRulesBody,
    buildClineAgentsMdBody,
    buildClinePreToolUseHook,
    writeClineArtifacts,
    mergeGsdAgentsMd,
    GSD_CURSOR_SESSION_HOOK_SCRIPT,
    GSD_CURSOR_POST_TOOL_HOOK_SCRIPT,
    GSD_CURSOR_HOOK_MARKER,
    buildCursorHookEntry,
    isManagedCursorHookEntry,
    reconcileCursorHooksJson,
    writeCursorHooksJson,
    removeCursorHooksJson,
    stripGsdFromAgentsMd,
    GSD_AGENTS_MD_MARKER,
    GSD_AGENTS_MD_CLOSE_MARKER,
    writeManifest,
    saveLocalPatches,
    reportLocalPatches,
    validateHookFields,
    preserveUserArtifacts,
    restoreUserArtifacts,
    migrateLegacyDevPreferencesToSkill,
    populatePristineDir,
    USER_OWNED_ARTIFACTS,
    finishInstall,
    homePathCoveredByRc,
    maybeSuggestPathExport,
    runtimeMap,
    allRuntimes,
    selectRuntimesFromArgs,
    GSD_UNINSTALL_HOOKS,
    parseRuntimeInput,
    buildRuntimePromptText,
    buildUpdateBannerPromptText,
    parseUpdateBannerInput,
    buildUpdateBannerHookEntry,
    buildHookCommand,
    normalizeNodePath,
    resolveNodeRunner,
    rewriteLegacyManagedNodeHookCommands,
    buildCodexHookBlock,
    rewriteLegacyCodexHookBlock,
    buildCodexHookWindowsShimIR,
    ensureCodexHooksJsonSessionStart,
    ensureCodexHooksJsonEvent,
    removeCodexHooksJsonEvent,
    reconcileCodexHooksJsonEvent,
    readGsdCommandNames,
    installRuntimeArtifacts,
    installOpencodeFamilySkills,
    uninstallRuntimeArtifacts,
    parseConfigDirFromArgs,
    cleanupLegacyGsdCc,
    _applyRuntimeRewrites,
  };

// Main logic — only run when not loaded as a module for testing
if (require.main === module && !process.env.GSD_TEST_MODE) {
  if (hasDryRun) {
    // --dry-run: preview legacy cleanup and exit without installing.
    if (hasUninstall) {
      console.log('Note: --dry-run previews legacy get-shit-done-cc cleanup only; it does not preview --uninstall.');
    }
    console.log('Dry run — no files will be modified.\n');
    // cleanupLegacyGsdCc with dryRun:true is the single source of truth for
    // both the legacy artifacts and the per-package cache path — no duplicate
    // printing here.
    const { plan } = cleanupLegacyGsdCc({ dryRun: true });
    if (plan.length === 0) {
      console.log('  (no legacy get-shit-done-cc artifacts found)');
    }
    process.exit(0);
  } else if (hasSkillsRoot) {
    // Print the skills root directory for a given runtime (used by /gsd-sync-skills).
    // Usage: node install.js --skills-root <runtime>
    const runtimeArg = args[args.indexOf('--skills-root') + 1];
    if (!runtimeArg || runtimeArg.startsWith('--')) {
      console.error('Usage: node install.js --skills-root <runtime>');
      process.exit(1);
    }
    const skillsRoot = getGlobalSkillsBase(runtimeArg);
    if (skillsRoot === null) {
      console.error(`${runtimeArg} does not use a skills directory`);
      process.exit(1);
    }
    console.log(skillsRoot);
  } else if (hasGlobal && hasLocal) {
    console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
    process.exit(1);
  } else if (explicitConfigDir && hasLocal) {
    console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
    process.exit(1);
  } else if (hasUninstall) {
    if (!hasGlobal && !hasLocal) {
      console.error(`  ${yellow}--uninstall requires --global or --local${reset}`);
      process.exit(1);
    }
    const runtimes = selectedRuntimes.length > 0 ? selectedRuntimes : ['claude'];
    for (const runtime of runtimes) {
      uninstall(hasGlobal, runtime);
    }
  } else if (selectedRuntimes.length > 0) {
    if (!hasGlobal && !hasLocal) {
      promptLocation(selectedRuntimes);
    } else {
      installAllRuntimes(selectedRuntimes, hasGlobal, false);
    }
  } else if (hasGlobal || hasLocal) {
    // Default to Claude if no runtime specified but location is
    installAllRuntimes(['claude'], hasGlobal, false);
  } else {
    // Interactive
    if (!process.stdin.isTTY) {
      console.log(`  ${yellow}Non-interactive terminal detected, defaulting to Claude Code global install${reset}\n`);
      installAllRuntimes(['claude'], true, false);
    } else {
      promptRuntime((runtimes) => {
        promptLocation(runtimes);
      });
    }
  }

} // end of !GSD_TEST_MODE main logic block