@opengsd/gsd-core 1.7.0-rc.3 → 1.7.0-rc.5

package/bin/install.js

@@ -43,6 +43,7 @@ const {
   readBaseRefFromSettings,
 } = require('../gsd-core/bin/lib/worktree-base-ref.cjs');
 const { resolveInstallPlan } = require('../gsd-core/bin/lib/runtime-config-adapter-registry.cjs');
+const { createImperativeAdapter } = require('../gsd-core/bin/lib/adapter-imperative.cjs');
 const runtimeArtifactConversion = require('../gsd-core/bin/lib/runtime-artifact-conversion.cjs');
 // Canonical set of hook files shipped to users. Imported here so writeManifest()
 // records exactly the same set that build-hooks.js copies to hooks/dist/, making
@@ -101,6 +102,45 @@ 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: ';
+// Known scalar fields of Codex's `AgentsToml` struct (codex-rs/config/src/
+// config_toml.rs \u2014 `[agents]` table). Codex marks the struct
+// `#[schemars(deny_unknown_fields)]`, so a bare `[agents]` table is valid ONLY
+// when every direct key is one of these (named agent roles live in the flattened
+// `[agents.<name>]` sub-tables, a separate `AgentRoleToml`). GSD writes only
+// `max_depth` (ADR-1239 upgrade 2 / #2088); the full set is enumerated so the
+// schema check accepts a user's other legitimate AgentsToml scalars too.
+const CODEX_AGENTS_TOML_SCALAR_KEYS = new Set([
+  'max_threads',
+  'max_depth',
+  'job_max_runtime_seconds',
+  'interrupt_message',
+]);
+// GSD's managed dispatch-depth value. Codex's implicit default is also 1 (root
+// sessions start at depth 0); writing it EXPLICITLY pins the negotiated
+// `dispatch.maxDepth: 1` axis instead of relying on codex-cli's implicit default
+// (ADR-1239 upgrade 2 / #2088). Per the negotiated capability, GSD-hosted Codex
+// dispatch is single-level (maxDepth === 1 \u2192 `degradationFor` flattens waves).
+const GSD_CODEX_AGENTS_MAX_DEPTH = 1;
+// Codex hooks.json lifecycle events GSD registers beyond SessionStart (which has
+// its own dedicated path). This is Codex's OWN hook-event vocabulary (per
+// developers.openai.com/codex/config-reference), distinct from the cross-runtime
+// settings.json `extendedHookEvents` descriptor field (a claude/gemini-family
+// allowlist consumed only by hooksSurface==='settings-json' runtimes — Codex is
+// codex-hooks-json). All route through gsd-context-monitor.js. #772 wired the
+// first three; #2088 adds the remaining six documented events so GSD's monitor
+// fires at the same lifecycle points as in Claude Code. Install and uninstall
+// share this list so the registered set and the removed set never diverge.
+const CODEX_EXTENDED_HOOK_EVENTS = [
+  'SubagentStart',
+  'Stop',
+  'PostToolUse',
+  'PreToolUse',
+  'PermissionRequest',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'UserPromptSubmit',
+];
 // 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
@@ -126,6 +166,9 @@ function isCodexHooksFeatureKey(key) {
 //
 // Merge policy: additive, non-destructive \u2014 existing user entries are preserved;
 // GSD entries are appended only when not already present (idempotent).
+// The reference/default runtime (ADR-1239 reference host). Single-sourced here
+// instead of scattered literal 'claude' defaults/rosters (#2086).
+const DEFAULT_RUNTIME = 'claude';
 const GSD_CLAUDE_ALLOW_PERMISSIONS = Object.freeze([
   'Bash(npx gsd-core *)',
   'Read(.planning/*)',
@@ -212,12 +255,30 @@ const GSD_COPILOT_SESSION_HOOK_PWSH =
 // 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)
+// A `command` hook entry runs an external script. GSD registers six managed hooks
+// (AC4a upgrade, #2089 — ADR-1239):
+//   sessionStart   → gsd-cursor-session-start.js   (context injection)
+//   postToolUse    → gsd-cursor-post-tool.js        (STATE.md update monitor)
+//   preToolUse     → gsd-cursor-pre-tool.js         (write-path guard)
+//   stop           → gsd-cursor-stop.js             (verify-work reminder)
+//   subagentStart  → gsd-cursor-subagent-start.js   (subagent context injection)
+//   subagentStop   → gsd-cursor-subagent-stop.js    (subagent completion reminder)
 // 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';
+const GSD_CURSOR_PRE_TOOL_HOOK_SCRIPT = 'gsd-cursor-pre-tool.js';
+const GSD_CURSOR_STOP_HOOK_SCRIPT = 'gsd-cursor-stop.js';
+const GSD_CURSOR_SUBAGENT_START_HOOK_SCRIPT = 'gsd-cursor-subagent-start.js';
+const GSD_CURSOR_SUBAGENT_STOP_HOOK_SCRIPT = 'gsd-cursor-subagent-stop.js';
+// All GSD-managed Cursor hook scripts (used by uninstall cleanup).
+const GSD_CURSOR_HOOK_SCRIPTS = [
+  GSD_CURSOR_SESSION_HOOK_SCRIPT,
+  GSD_CURSOR_POST_TOOL_HOOK_SCRIPT,
+  GSD_CURSOR_PRE_TOOL_HOOK_SCRIPT,
+  GSD_CURSOR_STOP_HOOK_SCRIPT,
+  GSD_CURSOR_SUBAGENT_START_HOOK_SCRIPT,
+  GSD_CURSOR_SUBAGENT_STOP_HOOK_SCRIPT,
+];
 // Marker comment embedded in managed hook entries so GSD can find+remove them.
 const GSD_CURSOR_HOOK_MARKER = 'gsd-managed';
 
@@ -273,60 +334,20 @@ const {
 } = require(path.join(_gsdLibDir, 'model-catalog.cjs'));
 const {
   resolveTierEntry: gsdResolveTierEntry,
-  EFFORT_SET: GSD_EFFORT_SET,
 } = require(path.join(_gsdLibDir, 'model-resolver.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;
-}
+// #2071 — install-time effort resolution (readGsdEffectiveEffortConfig /
+// resolveInstallTimeEffort, plus their _getGsdEffortCatalog + _readGsdConfigFile
+// helpers) was extracted into the shipped gsd-core/bin/lib/install-effort-resolver.cjs
+// so `gsd-tools effort sync` can require it from the installed runtime instead of this
+// package-root bin/install.js, which the installer never copies (#2071 crash). The
+// installer imports it back here — single source of truth for both surfaces.
+const {
+  readGsdEffectiveEffortConfig,
+  resolveInstallTimeEffort,
+  _getGsdEffortCatalog,
+  _readGsdConfigFile,
+} = require(path.join(_gsdLibDir, 'install-effort-resolver.cjs'));
 
 const {
   MINIMAL_SKILL_ALLOWLIST,
@@ -350,6 +371,80 @@ try {
 } catch (_) {
   _capabilityRegistry = undefined;
 }
+
+// Fail-safe floor for the reference host's #338-privacy-critical behaviors, used
+// ONLY when the first-party capability registry cannot be loaded (a broken bundle).
+// Without it, a registry-load failure would make `_hostBehaviors('claude')` return
+// {} and silently route a claude LOCAL install to the repo-shared, committed
+// `settings.json` instead of the gitignored `settings.local.json` (#338) — leaking
+// engineer-specific absolute paths. Keyed by runtime id (a DATA lookup, not a
+// hardcoded string-equality branch) so behavior degrades CLOSED (safe), never open.
+// The live descriptor (capabilities/claude/capability.json) remains the source of
+// truth; this mirrors only the privacy-load-bearing subset. (ADR-1239 / #2086)
+const FALLBACK_HOST_BEHAVIORS = Object.freeze({
+  claude: Object.freeze({
+    settingsFileByScope: Object.freeze({ local: 'settings.local.json', global: 'settings.json' }),
+    permissionsSchema: 'claude',
+    sourceMarkerFile: '.gsd-source',
+  }),
+});
+
+/**
+ * Resolve a runtime's host behaviors from a capability registry, with the
+ * #338-privacy fail-safe floor when the registry (or the runtime's descriptor)
+ * is unavailable. Registry is passed in so this is unit-testable under a
+ * simulated registry-load failure. (ADR-1239 / #2086)
+ */
+function _resolveHostBehaviors(runtime, registry) {
+  const cap = registry && registry.runtimes && registry.runtimes[runtime];
+  const declared = cap && cap.runtime && cap.runtime.hostBehaviors;
+  if (declared) return declared;
+  return FALLBACK_HOST_BEHAVIORS[runtime] || {};
+}
+
+/**
+ * Host-specific install behaviors, declared on the runtime descriptor
+ * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors) instead of
+ * scattered `runtime === '<id>'` string checks (ADR-1239 / #2086). Returns {}
+ * for runtimes that declare none, so every behavior branch degrades to the
+ * generic path by default — EXCEPT the reference host's #338-critical keys, which
+ * fall back to FALLBACK_HOST_BEHAVIORS if the registry failed to load.
+ */
+function _hostBehaviors(runtime) {
+  return _resolveHostBehaviors(runtime, _capabilityRegistry);
+}
+
+/**
+ * Resolve the ACTUAL on-disk skills-install directory for a runtime, honoring a
+ * skills-kind `home` override (ADR-1239 upgrade 3 / #2088: e.g. Codex skills ->
+ * $HOME/.agents/skills instead of the runtime's configDir). Descriptor-driven
+ * (no runtime === '<id>' check) so the snapshot/rollback machinery and post-install
+ * verification look where the skills actually landed. Falls back to <targetDir>/skills.
+ */
+function _resolveSkillsRootDir(runtime, targetDir, scope) {
+  try {
+    const layout = resolveRuntimeArtifactLayout(runtime, targetDir, scope);
+    const skillsKind = layout.kinds.find((k) => k.kind === 'skills');
+    if (skillsKind) return path.join(skillsKind.home || targetDir, skillsKind.destSubpath);
+  } catch (_e) { /* fall through to the configDir default */ }
+  return path.join(targetDir, 'skills');
+}
+
+/**
+ * Construct the imperative Host-Integration adapter (ADR-1239 / #2086), FAIL-OPEN.
+ * `createImperativeAdapter` composes the capability registry via
+ * `loadRegistry({includeInstalled:true})`, which require()s several capability
+ * modules. If any is unavailable (e.g. a packaging regression), return null so
+ * the caller degrades to the engine directly rather than hard-crashing install/
+ * uninstall — matching the optional `capability-registry.cjs` load posture above.
+ */
+function _runtimeAdapter(runtime) {
+  try {
+    return createImperativeAdapter({ runtime });
+  } catch {
+    return null;
+  }
+}
 const {
   applyInstallerMigrationPlan,
   discoverInstallerMigrations,
@@ -434,7 +529,7 @@ if (hasMinimal && _profileArgRaw) {
 
 function selectRuntimesFromArgs(runtimeArgs) {
   if (runtimeArgs.includes('--all')) {
-    return ['claude', 'kimi', 'kilo', 'opencode', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline'];
+    return ['claude', 'kimi', 'kilo', 'opencode', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'zcode'];
   }
   if (runtimeArgs.includes('--both')) {
     return ['claude', 'opencode'];
@@ -456,6 +551,7 @@ function selectRuntimesFromArgs(runtimeArgs) {
   if (runtimeArgs.includes('--kimi')) selected.push('kimi');
   if (runtimeArgs.includes('--codebuddy')) selected.push('codebuddy');
   if (runtimeArgs.includes('--cline')) selected.push('cline');
+  if (runtimeArgs.includes('--zcode')) selected.push('zcode');
   return selected;
 }
 
@@ -579,7 +675,7 @@ const banner = '\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, Kimi CLI, Kilo, Codex, Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, Cline and CodeBuddy.\n';
+  '  development workflows for Claude Code, OpenCode, Kimi CLI, Kilo, Codex, Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, Cline, CodeBuddy and ZCode.\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
@@ -636,7 +732,7 @@ if (hasUninstall) {
 
 // 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}--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 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 / 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`);
+  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}--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}--zcode${reset}                  Install for ZCode 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 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 / 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);
 }
 
@@ -909,6 +1005,9 @@ function resolveKiloConfigPath(configDir) {
   return path.join(configDir, 'kilo.json');
 }
 
+// #2087 — attribution config-path resolvers, keyed by descriptor (hostBehaviors.attributionConfigResolver)
+const ATTRIBUTION_CONFIG_RESOLVERS = { opencode: resolveOpencodeConfigPath, kilo: resolveKiloConfigPath };
+
 /**
  * Strip JSONC comments (// and /* *​/) from a string to produce valid JSON.
  * Handles comments inside strings correctly (does not strip them).
@@ -1070,126 +1169,6 @@ function readGsdEffectiveModelOverrides(targetDir = null) {
   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).
@@ -1295,29 +1274,6 @@ const READONLY_AGENT_DISALLOWED_TOOLS = {
   'gsd-ui-auditor': 'Edit, MultiEdit',
 };
 
-/**
- * #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.
  *
@@ -1420,15 +1376,14 @@ function getCommitAttribution(runtime) {
 
   let result;
 
-  if (runtime === 'opencode' || runtime === 'kilo') {
-    const resolveConfigPath = runtime === 'opencode'
-      ? resolveOpencodeConfigPath
-      : resolveKiloConfigPath;
+  const _attrResolverKey = _hostBehaviors(runtime).attributionConfigResolver;
+  if (_attrResolverKey && ATTRIBUTION_CONFIG_RESOLVERS[_attrResolverKey]) {
+    const resolveConfigPath = ATTRIBUTION_CONFIG_RESOLVERS[_attrResolverKey];
     const config = readSettings(resolveConfigPath(getGlobalConfigDir(runtime, null)));
     result = (config && config.disable_ai_attribution === true) ? null : undefined;
-  } else if (runtime === 'claude') {
+  } else if (_hostBehaviors(runtime).attributionSource === 'settings-json-commit') {
     // Claude Code
-    const settings = readSettings(path.join(getGlobalConfigDir('claude', explicitConfigDir), 'settings.json'));
+    const settings = readSettings(path.join(getGlobalConfigDir(runtime, explicitConfigDir), 'settings.json'));
     if (!settings || !settings.attribution || settings.attribution.commit === undefined) {
       result = undefined;
     } else if (settings.attribution.commit === '') {
@@ -1896,7 +1851,7 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
   // 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`;
+  if (_hostBehaviors(runtime).skillFrontmatterVersion) 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.
@@ -3265,6 +3220,77 @@ function cleanupWindsurfLegacyDevinSkills(workspaceDir) {
   return removed;
 }
 
+/**
+ * Migrate a skills kind that moved to an alternate `home` (ADR-1239 split-home):
+ * remove now-stale `<prefix>*` skill dirs left at the OLD configDir-rooted
+ * location by installs from before the move. Without this, upgrading (e.g. Codex
+ * relocating skills to ~/.agents/skills) orphans the pre-move dirs at
+ * ~/.codex/skills. Only managed `<prefix>*` dirs are touched; user-owned content
+ * (non-prefixed dirs, gsd-dev-preferences, symlinks) is preserved. Fail-open.
+ * @param {string} oldSkillsDir absolute path to the pre-move skills location
+ * @param {string} prefix managed skill-dir prefix (e.g. 'gsd-')
+ * @returns {number} count of stale dirs removed
+ */
+function cleanupMovedSkillsOldLocation(oldSkillsDir, prefix) {
+  if (!fs.existsSync(oldSkillsDir)) return 0;
+
+  // Mirror the user-owned list from cleanupCodexSkillMetadataSidecars (#2973).
+  const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
+  let removed = 0;
+
+  for (const entry of fs.readdirSync(oldSkillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
+    if (_userOwnedSkillDirs.has(entry.name)) continue;
+
+    const dirToRemove = path.join(oldSkillsDir, entry.name);
+    try {
+      // Symlink guard (mirrors cleanupWindsurfLegacyDevinSkills): never delete
+      // through a symlinked gsd-* dir — it could escape the tree.
+      const stat = fs.lstatSync(dirToRemove);
+      if (stat.isSymbolicLink()) continue;
+
+      fs.rmSync(dirToRemove, { recursive: true, force: true });
+      removed++;
+    } catch (_err) {
+      // Fail open — a single bad dir must not block install/uninstall.
+    }
+  }
+
+  // Prune the old skills dir if now empty — leaves the configHome clean.
+  // Never remove a non-empty container (user may keep other content there).
+  try {
+    if (fs.existsSync(oldSkillsDir) && fs.readdirSync(oldSkillsDir).length === 0) {
+      fs.rmdirSync(oldSkillsDir);
+    }
+  } catch (_err) {
+    // best-effort container cleanup
+  }
+
+  return removed;
+}
+
+/**
+ * When a runtime's skills kind declares an alternate `home` (split-home move),
+ * return the now-stale configDir-rooted skills location that installs before the
+ * move used; null when no move is in effect (no home override, or home resolves
+ * to the same path). Descriptor-driven — no per-runtime hardcoding.
+ * @returns {string|null}
+ */
+function _resolveMovedSkillsOldDir(runtime, targetDir, scope) {
+  try {
+    const layout = resolveRuntimeArtifactLayout(runtime, targetDir, scope);
+    const skillsKind = layout.kinds.find((k) => k.kind === 'skills');
+    if (skillsKind && skillsKind.home) {
+      const oldDir = path.join(targetDir, skillsKind.destSubpath);
+      const newDir = path.join(skillsKind.home, skillsKind.destSubpath);
+      if (path.resolve(oldDir) !== path.resolve(newDir)) return oldDir;
+    }
+  } catch (_e) {
+    // No migration when the layout can't resolve — never block on this.
+  }
+  return null;
+}
+
 /**
  * Generate the GSD config block for Codex config.toml.
  * @param {Array<{name: string, description: string}>} agents
@@ -3280,6 +3306,17 @@ function generateCodexConfigBlock(agents, targetDir) {
     '',
   ];
 
+  // ADR-1239 upgrade 2 / #2088 — explicit dispatch tuning. Pin `max_depth` on the
+  // `[agents]` (AgentsToml) table rather than relying on codex-cli's implicit
+  // default, realizing the negotiated `dispatch.maxDepth: 1` axis. This bare
+  // `[agents]` scalar table coexists with the flattened `[agents.<name>]` role
+  // sub-tables below (validated by validateCodexConfigSchema, which permits a
+  // known-scalar-only `[agents]`). Emitted before the role tables so the parent
+  // table is opened first.
+  lines.push('[agents]');
+  lines.push(`max_depth = ${GSD_CODEX_AGENTS_MAX_DEPTH}`);
+  lines.push('');
+
   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
@@ -3293,6 +3330,52 @@ function generateCodexConfigBlock(agents, targetDir) {
   return lines.join('\n');
 }
 
+/**
+ * Extract a user's pre-existing AgentsToml scalar assignments from a bare
+ * `[agents]` table — every known scalar EXCEPT `max_depth` (which GSD manages
+ * and always re-emits as 1). Returned as raw `key = value` line strings so
+ * mergeCodexConfig can PRESERVE them in the managed block instead of silently
+ * dropping the user's tuning when the bare `[agents]` table is purged (#2088
+ * review finding: the loosened validator declares such a table legitimate, so
+ * install must not destroy it). Only the first bare `[agents]` section is read;
+ * `[agents.<name>]` role tables are ignored. Fail-open → [].
+ * @returns {string[]}
+ */
+function extractCodexUserAgentsScalars(content) {
+  const preserved = [];
+  let section;
+  try {
+    section = getTomlTableSections(content).find((s) => !s.array && s.path === 'agents');
+  } catch (_e) {
+    return preserved;
+  }
+  if (!section) return preserved;
+  const body = content.slice(section.headerEnd, section.end);
+  for (const record of getTomlLineRecords(body)) {
+    if (record.startsInMultilineString || record.tableHeader) continue;
+    const trimmed = record.text.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (!record.keySegments || record.keySegments.length !== 1) continue;
+    const key = record.keySegments[0];
+    if (key === 'max_depth') continue; // GSD-managed — GSD's value wins.
+    if (!CODEX_AGENTS_TOML_SCALAR_KEYS.has(key)) continue;
+    preserved.push(trimmed);
+  }
+  return preserved;
+}
+
+/**
+ * Splice preserved user AgentsToml scalar lines into the managed GSD config
+ * block, immediately after the `[agents]` header and before GSD's `max_depth`
+ * line. Operates on the pre-EOL-normalization block (LF joins), matching only
+ * the bare `[agents]` header (never `[agents.<name>]`). Returns the block
+ * unchanged when there is nothing to preserve or the anchor is absent.
+ */
+function spliceCodexAgentsScalars(block, scalarLines) {
+  if (!scalarLines || scalarLines.length === 0) return block;
+  return block.replace(/(\n\[agents\]\n)(max_depth = )/, `$1${scalarLines.join('\n')}\n$2`);
+}
+
 /**
  * Strip any managed GSD agent sections from a TOML string.
  *
@@ -3315,6 +3398,16 @@ function stripCodexGsdAgentSections(content) {
       return true;
     }
 
+    // GSD's managed `[agents]` scalar block (ADR-1239 upgrade 2 / #2088 — the
+    // `max_depth` dispatch-tuning table). Install purges any pre-existing bare
+    // `[agents]` and writes its own, so a known-scalar-only bare `[agents]` is
+    // GSD-owned; strip it on uninstall. (The marker path already removes it via
+    // the marker-to-EOF cut; this covers the no-marker fallback.)
+    if (!section.array && section.path === 'agents') {
+      const body = content.slice(section.headerEnd, section.end);
+      return codexBareAgentsHasOnlyKnownScalars(body);
+    }
+
     // Legacy `[[agents]]` array-of-tables (#2645) — only strip blocks whose
     // `name = "gsd-..."`, preserving user-authored [[agents]] entries.
     if (section.array && section.path === 'agents') {
@@ -3342,7 +3435,11 @@ function stripGsdFromCodexConfig(content) {
   const codexHooksOwnership = getManagedCodexHooksOwnership(content);
 
   if (markerIndex !== -1) {
-    // Has GSD marker — remove everything from marker to EOF
+    // Has GSD marker — remove everything from marker to EOF. First recover the
+    // user's own AgentsToml scalars (max_threads etc.) that install folded into
+    // the managed [agents] block (#2088), so a full install→uninstall cycle
+    // round-trips the user's tuning. GSD-managed max_depth is dropped.
+    const preservedScalars = extractCodexUserAgentsScalars(content.slice(markerIndex));
     let before = content.substring(0, markerIndex);
     before = stripCodexHooksFeatureAssignments(before, codexHooksOwnership);
     // Also strip GSD-injected feature keys above the marker (Case 3 inject)
@@ -3351,6 +3448,9 @@ function stripGsdFromCodexConfig(content) {
     before = before.replace(/^\[features\]\s*\n(?=\[|$)/m, '');
     before = before.replace(/^\[agents\]\s*\n(?=\[|$)/m, '');
     before = before.replace(/^(?:\r?\n)+/, '').trimEnd();
+    if (preservedScalars.length > 0) {
+      before = (before ? before + eol + eol : '') + '[agents]' + eol + preservedScalars.join(eol);
+    }
     if (!before) return null;
     return before + eol;
   }
@@ -3361,7 +3461,11 @@ function stripGsdFromCodexConfig(content) {
   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)
+  // #2088: recover the user's own AgentsToml scalars before the [agents] table is
+  // stripped, so they survive uninstall even in the no-marker fallback path.
+  const preservedScalars = extractCodexUserAgentsScalars(cleaned);
+
+  // Remove [agents.gsd-*] sections + the managed known-scalar [agents] table.
   cleaned = stripCodexGsdAgentSections(cleaned);
 
   // Remove [features] section if now empty (only header, no keys before next section)
@@ -3372,6 +3476,10 @@ function stripGsdFromCodexConfig(content) {
 
   cleaned = cleaned.replace(/^(?:\r?\n)+/, '').trimEnd();
 
+  if (preservedScalars.length > 0) {
+    cleaned = (cleaned ? cleaned + eol + eol : '') + '[agents]' + eol + preservedScalars.join(eol);
+  }
+
   if (!cleaned) return null;
   return cleaned + eol;
 }
@@ -4843,6 +4951,33 @@ function parseTomlToObject(content) {
  *   - `hooks.<Event>` MUST be an array of tables when present (Codex ≥0.124
  *     rejects bare `[hooks.<Event>]` single-bracket maps).
  */
+/**
+ * True when a bare `[agents]` table body contains ONLY known AgentsToml scalar
+ * keys (CODEX_AGENTS_TOML_SCALAR_KEYS) — i.e. it is a valid AgentsToml struct
+ * that Codex's `deny_unknown_fields` will accept, not the break-causing form
+ * (#2760) that carries an unknown key. Comments and blank lines are ignored; an
+ * empty body is trivially valid. Mirrors isLegacyGsdAgentsSection's line scan.
+ */
+function codexBareAgentsHasOnlyKnownScalars(body) {
+  const lineRecords = getTomlLineRecords(body);
+  for (const record of lineRecords) {
+    // Conservative reject of anything not positively a single known-scalar
+    // assignment. A multiline-string value cannot be a valid AgentsToml scalar
+    // (max_threads/max_depth/job_max_runtime_seconds are integers,
+    // interrupt_message is a bool — none are strings), so codex would reject it
+    // too; rejecting here is correct, not a false negative.
+    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 ||
+        !CODEX_AGENTS_TOML_SCALAR_KEYS.has(record.keySegments[0])) {
+      return false;
+    }
+  }
+  return true;
+}
+
 function validateCodexConfigSchema(content) {
   let parsed;
   try {
@@ -4871,10 +5006,21 @@ function validateCodexConfigSchema(content) {
     }
 
     if (!section.array && section.path === 'agents') {
-      return {
-        ok: false,
-        reason: 'bare [agents] table is invalid in current Codex schema (expected [agents.<name>] struct form)',
-      };
+      // #2760 rejected ALL bare `[agents]` tables because a bare table holding a
+      // non-AgentsToml key (`default = "x"`, a role name, etc.) triggers Codex's
+      // "invalid type: ..., expected struct AgentsToml" and breaks every CLI
+      // invocation. But a bare `[agents]` whose keys are all valid AgentsToml
+      // scalars (max_depth/max_threads/...) IS a valid struct — that is exactly
+      // GSD's managed `max_depth` dispatch-tuning block (ADR-1239 upgrade 2 /
+      // #2088), and a user's own scalar tuning. Permit known-scalar-only; still
+      // reject any bare `[agents]` carrying an unknown key.
+      const body = content.slice(section.headerEnd, section.end);
+      if (!codexBareAgentsHasOnlyKnownScalars(body)) {
+        return {
+          ok: false,
+          reason: 'bare [agents] table with a non-AgentsToml key is invalid in current Codex schema (expected [agents.<name>] struct form, or only AgentsToml scalars like max_depth/max_threads)',
+        };
+      }
     }
 
     // hooks.state.* is Codex's persistent hook-trust namespace (added in
@@ -5150,7 +5296,13 @@ function mergeCodexConfig(configPath, gsdBlock) {
 
   const existing = fs.readFileSync(configPath, 'utf8');
   const eol = detectLineEnding(existing);
-  const normalizedGsdBlock = gsdBlock.replace(/\r?\n/g, eol);
+  // #2088 review: the bare `[agents]` table is purged below (Case 2/3 via
+  // stripLeakedGsdCodexSections) to keep a single managed `[agents]`. Preserve
+  // the user's own AgentsToml scalar tuning (max_threads, job_max_runtime_seconds,
+  // interrupt_message — everything except GSD-managed max_depth) by re-emitting
+  // it inside the managed block, so install never silently drops it.
+  const mergedGsdBlock = spliceCodexAgentsScalars(gsdBlock, extractCodexUserAgentsScalars(existing));
+  const normalizedGsdBlock = mergedGsdBlock.replace(/\r?\n/g, eol);
   const markerIndex = existing.indexOf(GSD_CODEX_MARKER);
 
   // Case 2: Has GSD marker — truncate and re-append
@@ -6104,62 +6256,14 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
 // convertClaudeCommandToKiloSkill: moved to src/install-engine.cts (ADR-1239 Phase B).
 // Imported from installEngine above.
 
-/**
- * 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')
- */
 // applyOpencodeFamilyPathPrefix: moved to src/install-engine.cts (ADR-1239 Phase B).
 // Imported from installEngine above.
-
-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);
-    }
-  }
-}
+//
+// copyFlattenedCommands (OpenCode/Kilo flattened command/ writer): moved to
+// src/install-engine.cts as installOpencodeFamilyCommands (ADR-1239 / #2087).
+// OpenCode/Kilo installs now route through installRuntimeArtifacts's
+// combinedFamilyInstall path (installOpencodeFamilyArtifacts) instead of the
+// bespoke inline block that used to call this function.
 
 function listCodexSkillNames(skillsDir, prefix = 'gsd-') {
   if (!fs.existsSync(skillsDir)) return [];
@@ -6461,7 +6565,7 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       // copyWithPathReplacement is the emit path for gsd-core/workflows/*.md;
       // _applyRuntimeRewrites is NOT invoked here, so this is what makes the fix
       // live in real installs (it is a no-op for files without those lines).
-      if (runtime !== 'claude') {
+      if (!_hostBehaviors(runtime).authorsCanonicalWorkflow) {
         content = _stampNonClaudeRuntimeDefaults(content, runtime);
       }
 
@@ -6663,16 +6767,20 @@ const GSD_UNINSTALL_HOOKS = [
  * @param {boolean} isGlobal - Whether to uninstall from global or local
  * @param {string} runtime - Target runtime ('claude', 'opencode', 'codex', 'copilot')
  */
-function uninstall(isGlobal, runtime = 'claude') {
+function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
   const { isOpencode, isKilo, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   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).
+  // Descriptor-driven (ADR-1239 / #2090): cline local installs write to the
+  // project root (.clinerules/ lives at the root, not in a .cline/ subdir),
+  // mirroring the install() path resolution (#787). Folded from a hardcoded
+  // `runtime === 'cline'` branch into hostBehaviors.localTargetIsProjectRoot.
   const targetDir = isGlobal
     ? getGlobalConfigDir(runtime, explicitConfigDir)
-    : runtime === 'cline'
+    : _hostBehaviors(runtime).localTargetIsProjectRoot
       ? process.cwd()
       : path.join(process.cwd(), dirName);
 
@@ -6721,11 +6829,34 @@ function uninstall(isGlobal, runtime = 'claude') {
 
   // 1. Remove GSD commands/skills (layout-driven)
   const scope = isGlobal ? 'global' : 'local';
-  uninstallRuntimeArtifacts(runtime, targetDir, scope);
+  // ADR-1239 / #2086: drive uninstall through the public Host-Integration Interface.
+  // Fail-open to the engine directly if the composed-registry adapter can't load.
+  const _uninstallAdapter = _runtimeAdapter(runtime);
+  if (_uninstallAdapter) {
+    _uninstallAdapter.uninstall({ configDir: targetDir, scope });
+  } else {
+    uninstallRuntimeArtifacts(runtime, targetDir, scope);
+  }
   removedCount++;
 
+  // ADR-1239 split-home migration: the adapter/plan uninstall targets the new
+  // `home` location (e.g. Codex → ~/.agents/skills). A user who installed
+  // BEFORE the move and never reinstalled still has managed gsd-* skill dirs at
+  // the old configDir-rooted location (~/.codex/skills) — remove those too so
+  // uninstall leaves nothing behind. User-owned content is preserved.
+  {
+    const _movedOldSkillsDir = _resolveMovedSkillsOldDir(runtime, targetDir, scope);
+    if (_movedOldSkillsDir) {
+      const migrated = cleanupMovedSkillsOldLocation(_movedOldSkillsDir, 'gsd-');
+      if (migrated > 0) {
+        removedCount++;
+        console.log(`  ${green}✓${reset} Removed ${migrated} legacy skill dir(s) from ${_movedOldSkillsDir}`);
+      }
+    }
+  }
+
   // 1a. Non-layout Codex side-effects: agent .toml files, config.toml sections, hooks.json
-  if (isCodex) {
+  if (_hostBehaviors(runtime).tomlConfigInstall) {
     const codexAgentsDir = path.join(targetDir, 'agents');
     if (fs.existsSync(codexAgentsDir)) {
       const tomlFiles = fs.readdirSync(codexAgentsDir);
@@ -6764,8 +6895,10 @@ function uninstall(isGlobal, runtime = 'claude') {
       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']) {
+    // #772/#2088: remove every managed Codex extended hook-event registration.
+    // Shares CODEX_EXTENDED_HOOK_EVENTS with the install loop — removal set ==
+    // registration set, so no managed event is ever orphaned.
+    for (const eventName of CODEX_EXTENDED_HOOK_EVENTS) {
       const eventCleanup = removeCodexHooksJsonEvent(targetDir, eventName);
       if (eventCleanup.changed) {
         removedCount++;
@@ -6812,7 +6945,9 @@ function uninstall(isGlobal, runtime = 'claude') {
   // 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') {
+  // Descriptor-driven (ADR-1239 / #2090): folded from `runtime === 'cline'`
+  // into hostBehaviors.clineRulesSurface.
+  if (_hostBehaviors(runtime).clineRulesSurface) {
     const clinerulesDir = path.join(targetDir, '.clinerules');
     for (const rel of ['gsd.md', path.join('hooks', 'PreToolUse')]) {
       const p = path.join(clinerulesDir, rel);
@@ -6858,17 +6993,20 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
-  // 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) {
+  // 1b-cursor. Descriptor-driven hook-bus cleanup (ADR-1239 / #2089): remove
+  // GSD-managed hook entries from hooks.json and clean up the managed hook
+  // scripts. Gated by the hostBehaviors.hooksJsonSurface descriptor axis, not a
+  // hardcoded `isCursor` branch.
+  if (_hostBehaviors(runtime).hooksJsonSurface) {
     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).
+    // Remove all GSD-managed hook scripts (sessionStart, postToolUse, preToolUse,
+    // stop, subagentStart, subagentStop — AC4a, #2089).
     const hooksDir = path.join(targetDir, 'hooks');
-    for (const script of [GSD_CURSOR_SESSION_HOOK_SCRIPT, GSD_CURSOR_POST_TOOL_HOOK_SCRIPT]) {
+    for (const script of GSD_CURSOR_HOOK_SCRIPTS) {
       const p = path.join(hooksDir, script);
       try {
         if (fs.existsSync(p)) {
@@ -6887,7 +7025,7 @@ function uninstall(isGlobal, runtime = 'claude') {
 
   // 1c. Claude local: remove flat gsd-*.md commands from commands/ (current layout,
   //     #1367 fix). Also remove legacy commands/gsd/ subdirectory from prior installs.
-  if (!isGlobal && runtime === 'claude') {
+  if (!isGlobal && _hostBehaviors(runtime).localInstallStyle === 'legacy-flat') {
     const commandsDir = path.join(targetDir, 'commands');
     // Remove flat gsd-*.md files (current layout after #1367 fix)
     if (fs.existsSync(commandsDir)) {
@@ -6929,7 +7067,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   //     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) {
+  if (isQwen || _hostBehaviors(runtime).legacyCommandsGsdCleanup === true) {
     // 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,
@@ -7042,9 +7180,10 @@ function uninstall(isGlobal, runtime = 'claude') {
   // 4z. Remove the OpenCode native plugin adapter (#1914). Only GSD's own
   // plugin file is removed; the plugins/ dir is pruned only if it becomes
   // empty, preserving any user-authored OpenCode plugins.
-  if (isOpencode) {
-    const pluginsDir = path.join(targetDir, 'plugins');
-    const pluginPath = path.join(pluginsDir, 'gsd-core.js');
+  const _np = _hostBehaviors(runtime).nativePlugin;
+  if (_np) {
+    const pluginsDir = path.join(targetDir, _np.dir);
+    const pluginPath = path.join(pluginsDir, _np.file);
     if (fs.existsSync(pluginPath)) {
       try {
         fs.unlinkSync(pluginPath);
@@ -7190,7 +7329,7 @@ function uninstall(isGlobal, runtime = 'claude') {
     // 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) {
+    if (_hostBehaviors(runtime).permissionsSchema === 'claude' && settings.permissions) {
       let permissionsModified = false;
       if (Array.isArray(settings.permissions.allow)) {
         const before = settings.permissions.allow.length;
@@ -7223,7 +7362,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   }
 
   // 6. For OpenCode, clean up permissions from opencode.json or opencode.jsonc
-  if (isOpencode) {
+  if (resolveInstallPlan(runtime).finishPermissionWriter === 'opencode') {
     const configPath = resolveOpencodeConfigPath(targetDir);
     if (fs.existsSync(configPath)) {
       try {
@@ -7665,19 +7804,24 @@ function resolveInstallRelativePath(baseDir, relPath) {
 /**
  * Write file manifest after installation for future modification detection
  */
-function writeManifest(configDir, runtime = 'claude', options = {}) {
+function writeManifest(configDir, runtime = DEFAULT_RUNTIME, options = {}) {
   const { isOpencode, isKilo, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const gsdDir = path.join(configDir, 'gsd-core');
   // #1367: Claude local now writes flat gsd-*.md files at commands/ (not commands/gsd/).
   // Claude local uses flatCommandsDir instead for manifest recording.
   const flatCommandsDir = path.join(configDir, 'commands');
-  const opencodeCommandDir = path.join(configDir, 'command');
-  // Hermes nests GSD skills under skills/gsd/ as a single category (#2841).
+  const opencodeCommandDir = path.join(configDir, _hostBehaviors(runtime).flatCommandDir || 'command');
+  // Hermes nests GSD skills under skills/gsd/ as a single category (#2841) —
+  // already encoded in its layout descriptor's destSubpath ('skills/gsd').
   // 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/';
+  // ADR-1239 upgrade 3 (#2088): honor a skills-kind `home` override (e.g. Codex
+  // skills -> $HOME/.agents/skills instead of configDir/skills) via the same
+  // descriptor-driven helper used by the snapshot/rollback/verification paths,
+  // so the manifest records what's actually on disk. _resolveSkillsRootDir already
+  // resolves destSubpath (which includes hermes's 'skills/gsd' nesting) — do not
+  // re-append 'gsd' or the hermes dir gets double-nested to skills/gsd/gsd.
+  const codexSkillsDir = _resolveSkillsRootDir(runtime, configDir, options.scope === 'local' ? 'local' : 'global');
+  const codexSkillsManifestPrefix = _hostBehaviors(runtime).skillsManifestPrefix || 'skills/';
   const agentsDir = path.join(configDir, 'agents');
   const manifest = {
     version: pkg.version,
@@ -7703,21 +7847,21 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
   // Claude local (#1367): flat gsd-*.md files at commands/ level.
   // Only claude local writes gsd-*.md here; global installs don't emit commands,
   // so this branch is a no-op for global (no matching files to find).
-  if (runtime === 'claude' && fs.existsSync(flatCommandsDir)) {
+  if (_hostBehaviors(runtime).localInstallStyle === 'legacy-flat' && fs.existsSync(flatCommandsDir)) {
     for (const file of fs.readdirSync(flatCommandsDir)) {
       if (file.startsWith('gsd-') && file.endsWith('.md')) {
         manifest.files['commands/' + file] = fileHash(path.join(flatCommandsDir, file));
       }
     }
   }
-  if ((isOpencode || isKilo) && fs.existsSync(opencodeCommandDir)) {
+  if (_hostBehaviors(runtime).flatCommandDir && 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) && fs.existsSync(codexSkillsDir)) {
+  if (!_hostBehaviors(runtime).skipCodexSkillsManifest && fs.existsSync(codexSkillsDir)) {
     // All runtimes (including Hermes post-#947) use the canonical 'gsd-' prefix.
     const skillListPrefix = 'gsd-';
     for (const skillName of listCodexSkillNames(codexSkillsDir, skillListPrefix)) {
@@ -7727,8 +7871,8 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
         manifest.files[`${codexSkillsManifestPrefix}${skillName}/${rel}`] = hash;
       }
     }
-    // For Hermes, also hash the category DESCRIPTION.md so reinstall detects drift.
-    if (isHermes) {
+    // Descriptor-driven (#2090): hash the category DESCRIPTION.md so reinstall detects drift.
+    if (_hostBehaviors(runtime).trackCategoryDescription) {
       const descPath = path.join(codexSkillsDir, 'DESCRIPTION.md');
       if (fs.existsSync(descPath)) {
         manifest.files['skills/gsd/DESCRIPTION.md'] = fileHash(descPath);
@@ -7754,7 +7898,9 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
   // 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) {
+  // Descriptor-driven (ADR-1239 / #2090): folded from `isCline` into
+  // hostBehaviors.clineRulesSurface.
+  if (_hostBehaviors(runtime).clineRulesSurface) {
     for (const rel of ['.clinerules/gsd.md', '.clinerules/hooks/PreToolUse']) {
       const dest = path.join(configDir, rel);
       if (fs.existsSync(dest)) {
@@ -7765,7 +7911,9 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
 
   // 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) {
+  // Descriptor-driven (ADR-1239 / #2089+#2090): cline's exclusion is via
+  // hostBehaviors.skipSharedHooksInstall (was hardcoded !isCline).
+  if (!isCodex && !isCopilot && _hostBehaviors(runtime).skipSharedHooksInstall !== true && !isWindsurf && !isTrae && !isKimi) {
     const hooksDir = path.join(configDir, 'hooks');
     if (fs.existsSync(hooksDir)) {
       // Drive from INSTALLED_HOOK_FILES (the canonical HOOKS_TO_COPY set from
@@ -7829,10 +7977,11 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
 
   // Track the OpenCode native plugin adapter (#1914) so update/drift detection
   // and uninstall can account for it.
-  if (isOpencode) {
-    const pluginInstallPath = path.join(configDir, 'plugins', 'gsd-core.js');
+  const _npM = _hostBehaviors(runtime).nativePlugin;
+  if (_npM) {
+    const pluginInstallPath = path.join(configDir, _npM.dir, _npM.file);
     if (fs.existsSync(pluginInstallPath)) {
-      manifest.files['plugins/gsd-core.js'] = fileHash(pluginInstallPath);
+      manifest.files[`${_npM.dir}/${_npM.file}`] = fileHash(pluginInstallPath);
     }
   }
 
@@ -8116,7 +8265,7 @@ function saveLocalPatches(configDir, pristineCtx) {
 /**
  * After install, report backed-up patches for user to reapply.
  */
-function reportLocalPatches(configDir, runtime = 'claude') {
+function reportLocalPatches(configDir, runtime = DEFAULT_RUNTIME) {
   const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
   const metaPath = path.join(patchesDir, 'backup-meta.json');
   if (!fs.existsSync(metaPath)) return [];
@@ -8125,15 +8274,11 @@ function reportLocalPatches(configDir, runtime = 'claude') {
   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 === 'codex'
-        ? '$gsd-update --reapply'
-        : runtime === 'cursor'
-          ? 'gsd-update --reapply (mention the skill name)'
-        : runtime === 'kimi'
-          ? '/skill:gsd-update --reapply'
-          : '/gsd-update --reapply';
+    const reapplyCommand = _hostBehaviors(runtime).reapplyCommand
+      ? _hostBehaviors(runtime).reapplyCommand
+      : 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) {
@@ -8159,8 +8304,8 @@ function reportInstallerMigrationResult(result) {
   }
 }
 
-function install(isGlobal, runtime = 'claude', options = {}) {
-  const { isOpencode, isKilo, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
+function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
+  const { isOpencode, isKilo, isZcode, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const plan = resolveInstallPlan(runtime);
   const dirName = getDirName(runtime);
   const src = path.join(__dirname, '..');
@@ -8213,15 +8358,17 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   };
 
   // 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.
+  // Descriptor-driven (ADR-1239 / #2090): cline local installs write to the
+  // project root (like Claude Code) — .clinerules lives at the root, not inside
+  // a .cline/ subdirectory. Folded from `isCline` into
+  // hostBehaviors.localTargetIsProjectRoot.
   // #791: antigravity local installs write to .agents/ (canonical). The legacy .agent/
   // directory is recognized by RUNTIME_DIRS (update-context) and _LEGACY_SCAN_SUBDIR_NAMES
   // but NOT auto-removed here; legacy .agent/ gsd artifacts are recognized but not
   // auto-removed on reinstall (dual-read fallback per issue #791 spec).
   const targetDir = isGlobal
     ? getGlobalConfigDir(runtime, explicitConfigDir)
-    : isCline
+    : _hostBehaviors(runtime).localTargetIsProjectRoot
       ? process.cwd()
       : path.join(process.cwd(), dirName);
 
@@ -8300,7 +8447,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   const isWindowsHost = process.platform === 'win32';
   const pathPrefix = computePathPrefix({
     isGlobal,
-    isOpencode,
+    isOpencode: _hostBehaviors(runtime).skipHomePrefixSubstitution === true,
     isWindowsHost,
     resolvedTarget,
     homeDir,
@@ -8366,8 +8513,8 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // Map<filename, Buffer> — content snapshot of each pre-existing gsd-* agent file.
   const codexPreInstallAgentContents = new Map();
   let codexPreInstallVersionBytes = null;
-  if (isCodex && !isMinimalMode(_effectiveInstallMode)) {
-    const _preSkillsDir = path.join(targetDir, 'skills');
+  if (_hostBehaviors(runtime).tomlConfigInstall && !isMinimalMode(_effectiveInstallMode)) {
+    const _preSkillsDir = _resolveSkillsRootDir(runtime, targetDir, isGlobal ? 'global' : 'local');
     if (fs.existsSync(_preSkillsDir)) {
       for (const entry of fs.readdirSync(_preSkillsDir, { withFileTypes: true })) {
         if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
@@ -8420,10 +8567,10 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // 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 : () => {
+  const _codexPreConfigRollback = !_hostBehaviors(runtime).tomlConfigInstall || isMinimalMode(_effectiveInstallMode) ? null : () => {
     rollbackInstallerMigrations();
     // skills/gsd-* — pass 1: restore snapshot entries (may be absent if deleted mid-install).
-    const _earlySkillsDir = path.join(targetDir, 'skills');
+    const _earlySkillsDir = _resolveSkillsRootDir(runtime, targetDir, isGlobal ? 'global' : 'local');
     for (const skillName of codexPreInstallSkillNames) {
       const skillDirPath = path.join(_earlySkillsDir, skillName);
       const fileMap = codexPreInstallSkillContents.get(skillName);
@@ -8586,23 +8733,58 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   //   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
-  //   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);
+  // Descriptor-driven (ADR-1016 / ADR-1239): a runtime takes the layout-driven
+  // installRuntimeArtifacts path when its scoped artifactLayout is non-empty
+  // (it declares any skills/commands/agents/kimi-agents kind for this scope).
+  // This replaces the prior hardcoded `isCodex || isCopilot || ...` roster so a
+  // newly-added runtime with an artifact layout installs without a per-runtime
+  // branch — the add-a-host tax ADR-1239 Phase B retires. OpenCode/Kilo now
+  // route through this SAME path too: their hostBehaviors.combinedFamilyInstall
+  // flag makes installRuntimeArtifacts (in src/install-engine.cts) delegate to
+  // installOpencodeFamilyArtifacts for the combined commands+skills+native-plugin
+  // install (ADR-1239 / #2087), replacing the bespoke inline block this comment
+  // used to describe. Claude-local remains the one special-cased path
+  // (copyWithPathReplacement + stale-skills cleanup).
+  const _isSkillsRuntime = (() => {
+    if (_hostBehaviors(runtime).localInstallStyle === 'legacy-flat' && !isGlobal) return false;  // legacy flat local path (descriptor-driven; #2086)
+    const cap = _capabilityRegistry && _capabilityRegistry.runtimes && _capabilityRegistry.runtimes[runtime];
+    const layout = cap && cap.runtime && cap.runtime.artifactLayout;
+    if (!layout) return false;
+    const scopeLayout = isGlobal ? layout.global : layout.local;
+    return Array.isArray(scopeLayout) && scopeLayout.length > 0;
+  })();
 
   if (_isSkillsRuntime) {
     // Layout-driven install for skills-based runtimes (full and minimal modes)
     const scope = isGlobal ? 'global' : 'local';
-    installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile, getCommitAttribution);
+    // ADR-1239 upgrade 3 / #2088: a kind may declare an alternate install `home`
+    // (e.g. Codex skills -> $HOME/.agents/skills) instead of the runtime's normal
+    // configDir. Resolve the ACTUAL on-disk skills root here, descriptor-driven
+    // (no isCodex check), so downstream sidecar-cleanup and post-install
+    // verification look in the right place regardless of which runtime declares
+    // an alternate home for its skills kind.
+    const _skillsRootDir = _resolveSkillsRootDir(runtime, targetDir, scope);
+    // ADR-1239 / #2086: drive install through the public Host-Integration Interface
+    // (imperative adapter). The adapter delegates to the SAME installRuntimeArtifacts
+    // engine call -> byte-identical output (gated by golden-install-parity). Fail-open
+    // to the engine directly if the composed-registry adapter can't load.
+    const _adapter = _runtimeAdapter(runtime);
+    if (_adapter) {
+      _adapter.install({
+        configDir: targetDir,
+        scope,
+        resolvedProfile: _resolvedProfile,
+        resolveAttribution: getCommitAttribution,
+      });
+    } else {
+      installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile, getCommitAttribution);
+    }
 
     // #1326 — Codex only: remove stale agents/openai.yaml sidecars from managed
     // gsd-* skill dirs. Prior installs wrote these files so Codex would show a
@@ -8610,8 +8792,23 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // index BOTH SKILL.md and the sidecar, causing each GSD skill to appear twice
     // in autocomplete. Cleaning them up fixes the duplication; SKILL.md alone is
     // sufficient for Codex discovery. User-owned dirs are never touched.
-    if (isCodex) {
-      cleanupCodexSkillMetadataSidecars(path.join(targetDir, 'skills'));
+    if (_hostBehaviors(runtime).cleanupSkillSidecars) {
+      cleanupCodexSkillMetadataSidecars(_skillsRootDir);
+    }
+
+    // ADR-1239 split-home migration: when a runtime's skills kind moved to an
+    // alternate `home` (e.g. Codex → ~/.agents/skills), pre-move installs left
+    // managed gsd-* skill dirs at the old configDir-rooted location
+    // (~/.codex/skills). Reinstalling here writes the new location but would
+    // otherwise orphan the old one — clean up the stale gsd-* dirs.
+    {
+      const _movedOldSkillsDir = _resolveMovedSkillsOldDir(runtime, targetDir, scope);
+      if (_movedOldSkillsDir) {
+        const migrated = cleanupMovedSkillsOldLocation(_movedOldSkillsDir, 'gsd-');
+        if (migrated > 0) {
+          console.log(`  ${green}✓${reset} Migrated ${migrated} skill dir(s) off the legacy ${_movedOldSkillsDir} location`);
+        }
+      }
     }
 
     // #1629 Finding B: Windsurf local only — remove legacy .devin/skills/gsd-*
@@ -8625,13 +8822,13 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       }
     }
 
-    // Hermes only: write DESCRIPTION.md for the gsd/ category after layout install
-    if (isHermes) {
+    // Descriptor-driven (#2090): write DESCRIPTION.md for the gsd/ category after layout install
+    if (_hostBehaviors(runtime).writeCategoryDescription) {
       writeHermesCategoryDescription(path.join(targetDir, 'skills', 'gsd'));
     }
 
     // Verify installed artifacts and report
-    if (isHermes) {
+    if (_hostBehaviors(runtime).reportSkillsCount) {
       const hermesSkillsDir = path.join(targetDir, 'skills', 'gsd');
       if (fs.existsSync(hermesSkillsDir)) {
         // Hermes layout uses prefix: 'gsd-' (#947) — skill dirs have gsd-<stem> names
@@ -8683,7 +8880,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         }
       }
     } else {
-      const skillsDir = path.join(targetDir, 'skills');
+      const skillsDir = _skillsRootDir;
       if (fs.existsSync(skillsDir)) {
         const count = fs.readdirSync(skillsDir, { withFileTypes: true })
           .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
@@ -8711,8 +8908,9 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         }
       }
 
-      // Cursor only: also report the commands/ output (#785 — Cursor 1.6 slash commands)
-      if (isCursor) {
+      // Descriptor-driven commands/ output report (#785 — Cursor 1.6 slash commands).
+      // Gated by hostBehaviors.reportCommandsDir, not a hardcoded `isCursor` branch (#2089).
+      if (_hostBehaviors(runtime).reportCommandsDir) {
         const commandsDir = path.join(targetDir, 'commands');
         if (fs.existsSync(commandsDir)) {
           const cmdCount = fs.readdirSync(commandsDir)
@@ -8743,68 +8941,12 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         }
       }
     }
-  } 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, getCommitAttribution);
-    if (_skillCount > 0) {
-      console.log(`  ${green}✓${reset} Installed ${_skillCount} skills to skills/`);
-    } else {
-      failures.push('skills/gsd-*');
-    }
-
-    // OpenCode-only: install the native plugin adapter (#1914). OpenCode
-    // declares hooksSurface: 'none', so GSD's lifecycle hooks are never
-    // registered as settings.json hooks the way Claude Code does — the hook
-    // *scripts* ship to <configDir>/hooks/ but nothing invokes them. This
-    // plugin bridges OpenCode's event bus onto those existing hook scripts
-    // (prompt guard, read guard, injection scanner, context monitor, ...),
-    // spawning them as subprocesses. OpenCode auto-discovers plugin files under
-    // <configDir>/plugins/ at startup — no opencode.json registration needed
-    // (its `plugin` array is for npm packages, not local file paths).
-    //
-    // The file MUST land as `.js`: OpenCode's loader globs
-    // `{plugin,plugins}/*.{ts,js}` (verified against its source) — a `.cjs`
-    // extension would never be discovered. The config dir carries a
-    // `{"type":"commonjs"}` package.json (written above), so the `.js` file is
-    // interpreted as CommonJS, matching the adapter's module.exports/require.
-    // Kilo has no plugin surface, so this is gated to OpenCode only.
-    if (isOpencode) {
-      const pluginSrc = path.join(src, '.opencode', 'plugins', 'gsd-core.js');
-      const pluginDestDir = path.join(targetDir, 'plugins');
-      const pluginDest = path.join(pluginDestDir, 'gsd-core.js');
-      if (fs.existsSync(pluginSrc)) {
-        fs.mkdirSync(pluginDestDir, { recursive: true });
-        fs.copyFileSync(pluginSrc, pluginDest);
-        if (fs.existsSync(pluginDest)) {
-          console.log(`  ${green}✓${reset} Installed OpenCode plugin (bridges GSD hooks)`);
-        } else {
-          failures.push('plugins/gsd-core.js');
-        }
-      } else {
-        failures.push('plugins/gsd-core.js');
-      }
-    }
-  } else if (isCline) {
+  } else if (_hostBehaviors(runtime).localCommandsViaRules) {
     // 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).
+    // Descriptor-driven (ADR-1239 / #2090): folded from `isCline` into
+    // hostBehaviors.localCommandsViaRules.
     console.log(`  ${green}✓${reset} Cline: commands will be available via .clinerules`);
   } else {
     // Claude Code local: flat gsd-<cmd>.md layout — Claude Code registers
@@ -8902,11 +9044,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // other runtime/scope deploys commands/gsd, so its walk-up already resolves
   // and needs no marker. Guarded on source presence so a half-published
   // package never writes a dangling marker.
-  if (runtime === 'claude' && isGlobal) {
+  if (_hostBehaviors(runtime).sourceMarkerFile && isGlobal) {
     const gsdSourceCommands = path.join(src, 'commands', 'gsd');
     if (fs.existsSync(gsdSourceCommands)) {
       try {
-        fs.writeFileSync(path.join(targetDir, '.gsd-source'), gsdSourceCommands + '\n', 'utf8');
+        // ADR-1239 Phase B write-confinement: the descriptor-sourced marker filename
+        // must resolve under targetDir (parity with the other descriptor-driven writes).
+        const _markerPath = assertDestWithinConfigHome(targetDir, _hostBehaviors(runtime).sourceMarkerFile);
+        fs.writeFileSync(_markerPath, gsdSourceCommands + '\n', 'utf8');
       } catch (err) {
         // Non-fatal: install proceeds. But on the Claude-global layout walk-up
         // also fails (no commands/gsd source tree), so a silent write failure
@@ -8978,9 +9123,11 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // (by installRuntimeArtifacts at line 8912), which also performs its own
   // stale-file prune pass. The inline stale-removal + inline loop both skip them.
   // Trivial group (cursor/windsurf/augment/trae/codebuddy) cut over together.
-  // cline is excluded: it takes a rules-only local branch and has a local/global
-  // complication that the descriptor-driven path does not handle correctly.
-  const _DESCRIPTOR_AGENTS_RUNTIMES = new Set(['cursor', 'windsurf', 'augment', 'trae', 'codebuddy']);
+  // #1575: copilot and antigravity cut over — copilot gets .agent.md filename
+  // rename via _copyStaged(runtime); antigravity uses scope-aware converter.
+  // cline remains excluded: rules-only local branch + local/global complication
+  // that the descriptor-driven path does not handle correctly.
+  const _DESCRIPTOR_AGENTS_RUNTIMES = new Set(['cursor', 'windsurf', 'augment', 'trae', 'codebuddy', 'copilot', 'antigravity']);
 
   // Always remove stale gsd-* agents first so re-installing with
   // `--minimal` actually shrinks a previously-full install.
@@ -8991,7 +9138,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     for (const file of fs.readdirSync(agentsDest)) {
       if (
         file.startsWith('gsd-') &&
-        (file.endsWith('.md') || (isCodex && file.endsWith('.toml')))
+        (file.endsWith('.md') || (_hostBehaviors(runtime).agentTomlFiles && file.endsWith('.toml')))
       ) {
         fs.unlinkSync(path.join(agentsDest, file));
       }
@@ -9009,7 +9156,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // 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) {
+    if (_hostBehaviors(runtime).tomlConfigInstall) {
       const codexConfigPath = path.join(targetDir, 'config.toml');
       if (fs.existsSync(codexConfigPath)) {
         const existing = fs.readFileSync(codexConfigPath, 'utf8');
@@ -9044,7 +9191,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         }
         content = processAttribution(content, getCommitAttribution(runtime));
         // Convert frontmatter for runtime compatibility (agents need different handling)
-        if (isOpencode) {
+        if (_hostBehaviors(runtime).frontmatterDialect === 'opencode') {
           // 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.
@@ -9063,16 +9210,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
             }
           }
           content = convertClaudeToOpencodeFrontmatter(content, { isAgent: true, modelOverride: _ocModelOverride });
-        } else if (isKilo) {
+        } else if (_hostBehaviors(runtime).frontmatterDialect === 'kilo') {
           content = convertClaudeToKiloFrontmatter(content, { isAgent: true });
-        } else if (isCodex) {
+        } else if (_hostBehaviors(runtime).frontmatterDialect === 'codex') {
           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) {
@@ -9081,13 +9226,15 @@ function install(isGlobal, runtime = 'claude', options = {}) {
           content = convertClaudeAgentToTraeAgent(content);
         } else if (isCodebuddy) {
           content = convertClaudeAgentToCodebuddyAgent(content);
-        } else if (isCline) {
+        } else if (_hostBehaviors(runtime).frontmatterDialect === 'cline') {
+          // Descriptor-driven (ADR-1239 / #2090): folded from `isCline` into
+          // hostBehaviors.frontmatterDialect === 'cline'.
           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) {
+        } else if (_hostBehaviors(runtime).brandingRewrites) {
           content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
           content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
           content = content.replace(/\.claude\//g, '.hermes/');
@@ -9099,11 +9246,11 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         // 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 runtime-safe (no effort: key in source).
-        if (runtime === 'claude') {
+        if ((_hostBehaviors(runtime).agentFrontmatterExtensions || []).includes('effort')) {
           const _effortCfg = readGsdEffectiveEffortConfig(targetDir);
           const _agentName = entry.name.replace(/\.md$/, '');
           const _universalEffort = resolveInstallTimeEffort(_effortCfg, _agentName);
-          const _renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime('claude', _universalEffort).value;
+          const _renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime(runtime, _universalEffort).value;
           content = injectEffortFrontmatter(content, _renderedEffort);
           const _disallowedTools = READONLY_AGENT_DISALLOWED_TOOLS[_agentName];
           if (_disallowedTools) content = injectDisallowedToolsFrontmatter(content, _disallowedTools);
@@ -9147,7 +9294,17 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     failures.push('VERSION');
   }
 
-  if (!isCodex && !isCopilot && !isCursor && !isWindsurf && !isTrae && !isCline && !isKimi) {
+  // #1821: Kilo and ZCode declare hooksSurface:'none' AND have no plugin surface,
+  // so the staged hook scripts are dead weight for them — exclude both here.
+  // OpenCode also declares hooksSurface:'none' but is deliberately NOT excluded:
+  // its native plugin adapter (#1914, installed above under plugins/gsd-core.js)
+  // spawns the staged hooks/*.js scripts via OpenCode's event bus and needs both
+  // them and the CommonJS package.json marker written below.
+  // #2089: Cursor's exclusion is now descriptor-driven via
+  // hostBehaviors.skipSharedHooksInstall (was hardcoded !isCursor).
+  // #2090: Cline's exclusion is likewise descriptor-driven (cline declares
+  // skipSharedHooksInstall:true) — the redundant `&& !isCline` was removed.
+  if (!isCodex && !isCopilot && _hostBehaviors(runtime).skipSharedHooksInstall !== true && !isWindsurf && !isTrae && !isKimi && !isKilo && !isZcode) {
     // 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
@@ -9176,7 +9333,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
               content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
               content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
             }
-            if (isHermes) {
+            if (_hostBehaviors(runtime).brandingRewrites) {
               content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
               content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
             }
@@ -9238,12 +9395,16 @@ function install(isGlobal, runtime = 'claude', options = {}) {
 
   // 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.
+  // (Cursor uses standalone .js hook scripts registered via hooks.json — gated
+  // descriptor-driven via hostBehaviors.skipSharedHooksInstall, #2089; Cline likewise
+  // #2090; Codex uses hooks.json directly; the others skip hooks entirely); Kilo and
+  // ZCode also skip hooks entirely (hooksSurface:'none' with no plugin surface — #1821).
+  // OpenCode is NOT excluded: its #1914 plugin adapter spawns the staged hooks and
+  // requires hooks/lib/ helpers. None of the excluded runtimes must 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)) {
+  if (!isCodex && !isCopilot && _hostBehaviors(runtime).skipSharedHooksInstall !== true && !isWindsurf && !isTrae && !isKimi && !isKilo && !isZcode && fs.existsSync(hooksLibSrc)) {
     const hooksLibDest = path.join(targetDir, 'hooks', 'lib');
     fs.mkdirSync(hooksLibDest, { recursive: true });
     copyLibDir(hooksLibSrc, hooksLibDest, GSD_HOOK_LIB_FILES);
@@ -9370,14 +9531,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   }
 
   // Write file manifest for future modification detection
-  writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
+  writeManifest(targetDir, runtime, { mode: _effectiveInstallMode, scope: isGlobal ? 'global' : 'local' });
   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') {
+  if (!_hostBehaviors(runtime).ownsClaudePaths) {
     const leakedPaths = [];
     // Only scan files that were written by this install (manifest-tracked).
     // Scanning the entire targetDir can match user-authored content that
@@ -9513,7 +9674,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       //     (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');
+      const _rollbackSkillsDir = _resolveSkillsRootDir(runtime, targetDir, isGlobal ? 'global' : 'local');
       // 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);
@@ -9624,7 +9785,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       // 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 });
+      writeManifest(targetDir, runtime, { mode: _effectiveInstallMode, scope: isGlobal ? 'global' : 'local' });
     } else {
       console.log(`  ${dim}↳${reset} Skipping Codex agent config generation (minimal install)`);
     }
@@ -9764,24 +9925,23 @@ function install(isGlobal, runtime = 'claude', options = {}) {
           }
         }
 
-        // ── 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.
+        // ── Codex extended hook events (#772, #2088) ─────────────────────────
+        // Codex CLI stabilised a full hook-event set in rust-v0.137.0. GSD
+        // registers CODEX_EXTENDED_HOOK_EVENTS (#2088 adds the 6 documented
+        // events beyond the original #772 three) — all routed through
+        // gsd-context-monitor.js so context-headroom warnings surface at each
+        // lifecycle point: SubagentStart/SubagentStop (subagent open/close),
+        // Stop (final-response), PreToolUse/PostToolUse (tool boundaries),
+        // PermissionRequest (approval prompts), Pre/PostCompact (context
+        // compaction), and UserPromptSubmit (per-turn context injection). The
+        // context-monitor script decides per-payload what to do; unregistered
+        // events simply never fire.
         //
         // 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']) {
+          for (const codexEvent of CODEX_EXTENDED_HOOK_EVENTS) {
             const eventWrite = ensureCodexHooksJsonEvent(targetDir, codexEvent, {
               absoluteRunner: codexNodeRunner,
               platform: process.platform,
@@ -9793,7 +9953,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
             }
           }
         } else if (!codexNodeRunner) {
-          console.warn(`  ${yellow}⚠${reset}  Skipped Codex SubagentStart/Stop/PostToolUse hook registration — Node runner unavailable.`);
+          console.warn(`  ${yellow}⚠${reset}  Skipped Codex extended hook-event registration — Node runner unavailable.`);
         }
         // ── end Codex extended hook events ────────────────────────────────────
       }
@@ -9858,16 +10018,20 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   }
 
   if (plan.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, {});
+    // ADR-1239 / #2089: Cursor hooks.json driven by the descriptor-managed hook-bus
+    // adapter. Registers all 6 managed events (sessionStart, postToolUse, preToolUse,
+    // stop, subagentStart, subagentStop) via runtime-hooks-surface.cts, which reads
+    // the event list from the descriptor-driven adapter module.
+    const cursorHookResult = writeCursorHooksJson(targetDir, src, {
+      managedHookEvents: _hostBehaviors(runtime).managedHookEvents,
+    });
     if (cursorHookResult.changed) {
-      console.log(`  ${green}✓${reset} Configured Cursor lifecycle hooks (sessionStart, postToolUse)`);
+      console.log(`  ${green}✓${reset} Configured Cursor lifecycle hooks (sessionStart, postToolUse, preToolUse, stop, subagentStart, subagentStop)`);
     } 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 });
+    writeManifest(targetDir, runtime, { mode: _effectiveInstallMode, scope: isGlobal ? 'global' : 'local' });
     persistActiveProfileMarker();
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
@@ -9885,7 +10049,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     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 });
+    writeManifest(targetDir, runtime, { mode: _effectiveInstallMode, scope: isGlobal ? 'global' : 'local' });
     persistActiveProfileMarker();
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
@@ -9900,9 +10064,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // #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);
+  const _scopedSettings = _hostBehaviors(runtime).settingsFileByScope || null;
+  const isLocalClaude = (!isGlobal && !!(_scopedSettings && _scopedSettings.local));
+  const settingsFileName = isLocalClaude
+    ? _scopedSettings.local
+    : ((_scopedSettings && _scopedSettings.global) || 'settings.json');
+  // ADR-1239 Phase B write-confinement: the descriptor-sourced settings filename
+  // must resolve under targetDir (this path also drives a recursive mkdirSync).
+  const settingsPath = assertDestWithinConfigHome(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.
@@ -10085,7 +10254,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // 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
+  const updateBannerCommand = _hostBehaviors(runtime).skipUpdateBannerCommand
     ? null
     : (isGlobal
       ? buildHookCommand(targetDir, 'gsd-update-banner.js', hookOpts)
@@ -10168,11 +10337,11 @@ function install(isGlobal, runtime = 'claude', options = {}) {
 /**
  * Apply statusline config, then print completion message
  */
-function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true, configDir = null, bannerOpts = {}) {
+function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = DEFAULT_RUNTIME, isGlobal = true, configDir = null, bannerOpts = {}) {
   const { isOpencode, isKilo, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const plan = resolveInstallPlan(runtime);
 
-  if (shouldInstallStatusline && plan.writesSharedSettings && !isOpencode) {
+  if (shouldInstallStatusline && plan.writesSharedSettings && !_hostBehaviors(runtime).skipSettingsUi) {
     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
@@ -10198,7 +10367,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // 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 && plan.writesSharedSettings && !isOpencode) {
+  if (shouldInstallBanner && settings && plan.writesSharedSettings && !_hostBehaviors(runtime).skipSettingsUi) {
     if (!bannerCommand) {
       console.warn(`  ${yellow}⚠${reset}  Skipped update banner registration — Node executable path unavailable. See #2979 / #3002.`);
     } else {
@@ -10227,7 +10396,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // Merges GSD-owned entries non-destructively (preserves existing user permissions).
   // Scoped to Claude only: antigravity/qwen/hermes/codebuddy also write
   // settings.json but use different runtimes and do not use these permission strings.
-  if (runtime === 'claude') {
+  if (_hostBehaviors(runtime).permissionsSchema === 'claude') {
     mergeClaudePermissions(settings);
   }
 
@@ -10260,7 +10429,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // chat model instead of pinning the resolved model. See #1156 (default-to-omit
   // intent) and #1569 (preserve explicit true). Guard matches the #130-class pattern
   // on configureOpencodePermissions above.
-  if (runtime !== 'claude' && !process.env.GSD_TEST_MODE) {
+  if (!_hostBehaviors(runtime).nativeModelAliases && !process.env.GSD_TEST_MODE) {
     const gsdDir = path.join(os.homedir(), '.gsd');
     const defaultsPath = path.join(gsdDir, 'defaults.json');
     try {
@@ -10302,7 +10471,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // 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) {
+  if (_hostBehaviors(runtime).skillsGlobalOnboarding && 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.
 
@@ -10401,10 +10570,11 @@ const runtimeMap = {
   '12': 'opencode',
   '13': 'qwen',
   '14': 'trae',
-  '15': 'windsurf'
+  '15': 'windsurf',
+  '16': 'zcode'
 };
-const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kilo', 'opencode', 'qwen', 'trae', 'windsurf'];
-const ALL_RUNTIMES_OPTION = '16';
+const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kilo', 'opencode', 'qwen', 'trae', 'windsurf', 'zcode'];
+const ALL_RUNTIMES_OPTION = '17';
 
 /**
  * Build the runtime-selection prompt text shown by the interactive installer.
@@ -10427,7 +10597,8 @@ function buildRuntimePromptText() {
   ${cyan}13${reset}) Qwen Code    ${dim}(~/.qwen)${reset}
   ${cyan}14${reset}) Trae         ${dim}(~/.trae)${reset}
   ${cyan}15${reset}) Windsurf     ${dim}(~/.codeium/windsurf)${reset}
-  ${cyan}16${reset}) All
+  ${cyan}16${reset}) ZCode        ${dim}(~/.zcode)${reset}
+  ${cyan}17${reset}) All
 
   ${dim}Select multiple: 1,2,6 or 1 2 6${reset}
 `;
@@ -10459,7 +10630,7 @@ function parseRuntimeInput(answer) {
     }
   }
 
-  return selected.length > 0 ? selected : ['claude'];
+  return selected.length > 0 ? selected : [DEFAULT_RUNTIME];
 }
 
 function promptRuntime(callback) {
@@ -11078,7 +11249,7 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
     throw error;
   }
 
-  const statuslineRuntimes = ['claude'];
+  const statuslineRuntimes = [DEFAULT_RUNTIME];
   const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));
 
   const finalize = (shouldInstallStatusline, shouldInstallBanner) => {
@@ -11175,6 +11346,13 @@ module.exports = {
     generateCodexAgentToml,
     cleanupCodexSkillMetadataSidecars,
     cleanupWindsurfLegacyDevinSkills,
+    cleanupMovedSkillsOldLocation,
+    _resolveMovedSkillsOldDir,
+    _resolveSkillsRootDir,
+    codexBareAgentsHasOnlyKnownScalars,
+    extractCodexUserAgentsScalars,
+    spliceCodexAgentsScalars,
+    CODEX_EXTENDED_HOOK_EVENTS,
     generateCodexConfigBlock,
     stripGsdFromCodexConfig,
     migrateCodexHooksMapFormat,
@@ -11194,6 +11372,9 @@ module.exports = {
     install,
     installAllRuntimes,
     uninstall,
+    // #2086 — host-behavior resolution + the #338 privacy fail-safe floor (exported for tests)
+    _resolveHostBehaviors,
+    FALLBACK_HOST_BEHAVIORS,
     convertSlashCommandsToCodexSkillMentions,
     convertClaudeCommandToCodexSkill,
     convertClaudeCommandToKimiSkill,
@@ -11258,6 +11439,11 @@ module.exports = {
     mergeGsdAgentsMd,
     GSD_CURSOR_SESSION_HOOK_SCRIPT,
     GSD_CURSOR_POST_TOOL_HOOK_SCRIPT,
+    GSD_CURSOR_PRE_TOOL_HOOK_SCRIPT,
+    GSD_CURSOR_STOP_HOOK_SCRIPT,
+    GSD_CURSOR_SUBAGENT_START_HOOK_SCRIPT,
+    GSD_CURSOR_SUBAGENT_STOP_HOOK_SCRIPT,
+    GSD_CURSOR_HOOK_SCRIPTS,
     GSD_CURSOR_HOOK_MARKER,
     buildCursorHookEntry,
     isManagedCursorHookEntry,
@@ -11362,7 +11548,7 @@ if (require.main === module && !process.env.GSD_TEST_MODE) {
       console.error(`  ${yellow}--uninstall requires --global or --local${reset}`);
       process.exit(1);
     }
-    const runtimes = selectedRuntimes.length > 0 ? selectedRuntimes : ['claude'];
+    const runtimes = selectedRuntimes.length > 0 ? selectedRuntimes : [DEFAULT_RUNTIME];
     for (const runtime of runtimes) {
       uninstall(hasGlobal, runtime);
     }
@@ -11374,12 +11560,12 @@ if (require.main === module && !process.env.GSD_TEST_MODE) {
     }
   } else if (hasGlobal || hasLocal) {
     // Default to Claude if no runtime specified but location is
-    installAllRuntimes(['claude'], hasGlobal, false);
+    installAllRuntimes([DEFAULT_RUNTIME], 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);
+      installAllRuntimes([DEFAULT_RUNTIME], true, false);
     } else {
       promptRuntime((runtimes) => {
         promptLocation(runtimes);