@opengsd/gsd-core 1.7.0 → 1.9.0

package/bin/install.js

@@ -168,15 +168,28 @@ const DEFAULT_RUNTIME = 'claude';
 const GSD_CLAUDE_ALLOW_PERMISSIONS = Object.freeze([
   'Bash(npx gsd-core *)',
   'Read(.planning/*)',
-  'Write(.planning/*)',
+  'Edit(.planning/*)',
   'Read(STATE.md)',
-  'Write(STATE.md)',
+  'Edit(STATE.md)',
 ]);
 const GSD_CLAUDE_DENY_PERMISSIONS = Object.freeze([
   'Read(.env)',
   'Read(.env.*)',
   'Read(.secrets)',
 ]);
+// #2278 — Stale allow-rule forms from before the fix. Claude Code has no
+// standalone `Write` permission gate: file-editing tools (Write/Edit/
+// NotebookEdit) are gated collectively via `Edit(pattern)`. The original
+// `Write(.planning/*)` / `Write(STATE.md)` entries were therefore silently
+// unmatched (never granted anything) and Claude Code additionally surfaces a
+// session-start warning about unmatched permission rules. This list lets
+// mergeClaudePermissions and uninstall cleanup retire those stale entries on
+// existing installs while the current GSD_CLAUDE_ALLOW_PERMISSIONS above
+// carries the working `Edit(...)` forms.
+const GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS = Object.freeze([
+  'Write(.planning/*)',
+  'Write(STATE.md)',
+]);
 
 /**
  * Merge GSD-owned permission entries into a Claude Code settings object.
@@ -185,6 +198,12 @@ const GSD_CLAUDE_DENY_PERMISSIONS = Object.freeze([
  * entries are appended only if not already present. No other permission sub-keys
  * (ask, disableBypassPermissionsMode, etc.) are touched.
  *
+ * Migration (#2278): before adding the current GSD_CLAUDE_ALLOW_PERMISSIONS,
+ * any stale GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS entry (e.g. the unmatched
+ * `Write(...)` forms from before the fix) is removed from permissions.allow,
+ * so existing installs end up with the working `Edit(...)` forms instead of
+ * both the dead legacy entry and its replacement sitting side by side.
+ *
  * Defensive: if settings is not a plain object, returns immediately without
  * throwing. If permissions.allow / permissions.deny exist but are not arrays
  * (malformed settings), they are replaced with valid arrays.
@@ -205,6 +224,10 @@ function mergeClaudePermissions(settings) {
     settings.permissions.deny = [];
   }
 
+  settings.permissions.allow = settings.permissions.allow.filter(
+    (e) => !GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS.includes(e)
+  );
+
   for (const entry of GSD_CLAUDE_ALLOW_PERMISSIONS) {
     if (!settings.permissions.allow.includes(entry)) {
       settings.permissions.allow.push(entry);
@@ -302,7 +325,13 @@ const GSD_WINDSURF_HOOK_SCRIPTS = [
 
 // GSD-managed files under hooks/lib/ (helpers required by gsd-*.sh hooks).
 // git-cmd.js does not start with "gsd-" (shared classifier for #3129), gsd-graphify-rebuild.sh does.
-const GSD_HOOK_LIB_FILES = ['git-cmd.js', 'gsd-graphify-rebuild.sh'];
+// cursor-workspace.js (#2587) is required by the Cursor lifecycle hooks. Those
+// are staged individually by writeCursorHooksJson (Cursor sets
+// hostBehaviors.skipSharedHooksInstall, so it never reaches the bulk hooks/lib
+// copy below) — that function stages this helper alongside them. Listing it
+// here keeps uninstall and the manifest managing it for every OTHER runtime
+// that does receive hooks/lib.
+const GSD_HOOK_LIB_FILES = ['git-cmd.js', 'gsd-graphify-rebuild.sh', 'cursor-workspace.js'];
 
 const CODEX_AGENT_SANDBOX = {
   'gsd-executor': 'workspace-write',
@@ -352,6 +381,7 @@ const {
 } = require(path.join(_gsdLibDir, 'model-catalog.cjs'));
 const {
   resolveTierEntry: gsdResolveTierEntry,
+  CLAUDE_AGENT_ALIASES,
 } = require(path.join(_gsdLibDir, 'model-resolver.cjs'));
 
 // #2071 — install-time effort resolution (readGsdEffectiveEffortConfig /
@@ -390,6 +420,32 @@ try {
   _capabilityRegistry = undefined;
 }
 
+// #2322 BLOCKER 2: `_capabilityRegistry` above is the FROZEN first-party registry
+// (capability-registry.cjs, built at publish time) — it never reflects an
+// INSTALLED third-party overlay capability, so a fresh `gsd install` could never
+// stage an installed third-party capability's skill regardless of registration,
+// even on the DEFAULT `--profile full`. `_installedCapabilityRegistry` composes
+// the overlay via capability-loader's `loadRegistry({includeInstalled:true})` —
+// the SAME call capability-writer.cts's `capability set --runtime` path already
+// uses — so a fresh install and a post-install `capability set` agree on
+// third-party skill availability. Used ONLY for skill-profile resolution and
+// runtime-artifact-layout staging below; `_capabilityRegistry` (frozen) remains
+// the source for gsd-core's OWN runtime/host-behavior descriptors (unaffected —
+// those are always first-party). A load failure degrades to the frozen
+// `_capabilityRegistry` (no overlay data -> no third-party skills staged; never
+// a crash and never a scan-and-guess fallback).
+let _installedCapabilityRegistry;
+try {
+  const _capabilityLoader = require(path.join(_gsdLibDir, 'capability-loader.cjs'));
+  _installedCapabilityRegistry = _capabilityLoader.loadRegistry({
+    includeInstalled: true,
+    cwd: process.cwd(),
+    gsdHome: process.env['GSD_HOME'],
+  });
+} catch (_) {
+  _installedCapabilityRegistry = _capabilityRegistry;
+}
+
 // 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
@@ -441,6 +497,25 @@ function _hostBehaviors(runtime) {
   return _resolveHostBehaviors(runtime, _capabilityRegistry);
 }
 
+/**
+ * Read a runtime's documentation-sourced `hostIntegration.dispatch` axes
+ * (ADR-1239 Phase A — `capabilities/<runtime>/capability.json`
+ * `runtime.hostIntegration.dispatch`): `{namedDispatch, nested, maxDepth,
+ * background, backgroundDispatch, subagentToolkit}`. These are validated,
+ * closed-vocabulary FACTS about what the runtime's real dispatch primitive
+ * supports (never inferred) — see `docs/reference/host-integration-capability-
+ * matrix.md` for citations. Unlike `_hostBehaviors` (install *policy*), this is
+ * the negotiated *capability* surface; #2284 is its first content-projection
+ * consumer (previously read only by `shouldFlattenDispatch`). Returns `{}` if
+ * the registry or the runtime's descriptor is unavailable, so callers must
+ * treat every axis as absent/unknown (fail-closed) rather than assume a value.
+ */
+function _hostIntegrationDispatch(runtime) {
+  const cap = _capabilityRegistry && _capabilityRegistry.runtimes && _capabilityRegistry.runtimes[runtime];
+  const dispatch = cap && cap.runtime && cap.runtime.hostIntegration && cap.runtime.hostIntegration.dispatch;
+  return dispatch || {};
+}
+
 /**
  * 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 ->
@@ -510,6 +585,7 @@ const {
   _installNativePluginIfDeclared,
   _copyStaged,
   hasExistingSymlinkBetween,
+  isSymlinkedDestOptIn,
   preserveUserArtifacts,
   restoreUserArtifacts,
   migrateLegacyDevPreferencesToSkill,
@@ -557,7 +633,7 @@ if (hasMinimal && _profileArgRaw) {
 
 function selectRuntimesFromArgs(runtimeArgs) {
   if (runtimeArgs.includes('--all')) {
-    return ['claude', 'kimi', 'kilo', 'opencode', 'pi', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'zcode'];
+    return ['claude', 'kimi', 'kimi-code', 'kilo', 'opencode', 'pi', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'zcode'];
   }
   if (runtimeArgs.includes('--both')) {
     return ['claude', 'opencode'];
@@ -578,6 +654,7 @@ function selectRuntimesFromArgs(runtimeArgs) {
   if (runtimeArgs.includes('--qwen')) selected.push('qwen');
   if (runtimeArgs.includes('--hermes')) selected.push('hermes');
   if (runtimeArgs.includes('--kimi')) selected.push('kimi');
+  if (runtimeArgs.includes('--kimi-code')) selected.push('kimi-code');
   if (runtimeArgs.includes('--codebuddy')) selected.push('codebuddy');
   if (runtimeArgs.includes('--cline')) selected.push('cline');
   if (runtimeArgs.includes('--zcode')) selected.push('zcode');
@@ -587,6 +664,62 @@ function selectRuntimesFromArgs(runtimeArgs) {
 // Runtime selection - can be set by flags or interactive prompt
 let selectedRuntimes = selectRuntimesFromArgs(args);
 
+// #2505 Phase 5: Kimi variant disambiguation (#2513). Kimi CLI (Python, ~/.kimi/)
+// and Kimi Code (Node, ~/.kimi-code/) are two distinct Moonshot products that
+// share the "kimi" brand. Probe for each product's config.toml and warn when
+// the selected runtime doesn't match the detected install — catches the common
+// "ran --kimi --global but actually on Kimi Code" mistake that produced inert
+// YAMLs and empty agent-skills before the Phase 1 descriptor split.
+function disambiguateKimiVariant(runtimes) {
+  const home = os.homedir();
+  const hasKimiCli = fs.existsSync(path.join(home, '.kimi', 'config.toml'));
+  const hasKimiCode = fs.existsSync(path.join(home, '.kimi-code', 'config.toml'));
+  const notices = [];
+  if (runtimes.includes('kimi') && hasKimiCode && !hasKimiCli) {
+    notices.push({
+      kind: 'wrong-variant',
+      selected: 'kimi',
+      detected: 'kimi-code',
+      message: `Detected ~/.kimi-code/config.toml (Kimi Code, Node CLI) but not ~/.kimi/config.toml (Kimi CLI, Python). You selected --kimi but appear to be on Kimi Code. Re-run with --kimi-code for a working install. (Kimi CLI = Python kimi-cli with named subagents; Kimi Code = Node CLI with coder/explore/plan built-ins only.)`,
+    });
+  }
+  if (runtimes.includes('kimi-code') && hasKimiCli && !hasKimiCode) {
+    notices.push({
+      kind: 'wrong-variant',
+      selected: 'kimi-code',
+      detected: 'kimi',
+      message: `Detected ~/.kimi/config.toml (Kimi CLI, Python) but not ~/.kimi-code/config.toml (Kimi Code, Node CLI). You selected --kimi-code but appear to be on Kimi CLI. Re-run with --kimi for a working install.`,
+    });
+  }
+  // Distinct-entry descriptions when either Kimi variant is selected.
+  if (runtimes.includes('kimi')) {
+    notices.push({
+      kind: 'description',
+      runtime: 'kimi',
+      message: 'Kimi CLI (Python kimi-cli): named subagents via YAML, config at ~/.kimi/, hooks via ~/.kimi/config.toml [[hooks]].',
+    });
+  }
+  if (runtimes.includes('kimi-code')) {
+    notices.push({
+      kind: 'description',
+      runtime: 'kimi-code',
+      message: 'Kimi Code (Node CLI): three built-in subagents (coder/explore/plan), Agent Skills at ~/.kimi-code/skills/, config at ~/.kimi-code/.',
+    });
+  }
+  return notices;
+}
+
+if (selectedRuntimes.includes('kimi') || selectedRuntimes.includes('kimi-code')) {
+  const kimiNotices = disambiguateKimiVariant(selectedRuntimes);
+  for (const notice of kimiNotices) {
+    if (notice.kind === 'wrong-variant') {
+      console.error(`${yellow}⚠ Kimi variant mismatch (${notice.selected} → ${notice.detected}).${reset} ${notice.message}`);
+    } else if (notice.kind === 'description') {
+      console.log(`${dim}  ${notice.runtime}: ${notice.message}${reset}`);
+    }
+  }
+}
+
 // #1928: Google sunset Gemini CLI on 2026-06-18; Antigravity CLI is its
 // official successor. `--gemini` is no longer a valid runtime selector —
 // selectRuntimesFromArgs above no longer recognizes it, so it never lands in
@@ -2368,6 +2501,56 @@ function extractFrontmatterField(frontmatter, fieldName) {
   return match[1].trim().replace(/^['"]|['"]$/g, '');
 }
 
+// #2284 finding (b): the `<runtime_compatibility>` block appearing in
+// gsd-core/workflows/{plan-phase,execute-phase}.md is a runtime-COMPARISON
+// table ("**Claude Code:** Uses `Agent(...)`" / "a backgrounded Claude Code
+// agent" / "top-level Claude Code") — every "Claude Code" mention inside it
+// is a COMPARED-RUNTIME LABEL, not a host self-reference. The brand swap
+// below (`Claude Code` → the installing runtime's own display name) is
+// meant only for host self-references; applying it inside this block
+// mislabels the comparison (e.g. Windsurf installs would read "**Windsurf:**
+// Uses `Agent(...)`" describing what is actually Claude Code's behavior).
+// This is cross-cutting across every runtime that brand-swaps workflow
+// content (cursor/windsurf/trae/cline/codebuddy hardcoded; qwen/hermes
+// descriptor-driven via hostBehaviors.brandingRewrites) — confirmed to
+// reproduce on unmodified Windsurf, not Hermes-specific.
+const RUNTIME_COMPATIBILITY_BLOCK_RE = /<runtime_compatibility>[\s\S]*?<\/runtime_compatibility>/g;
+
+/**
+ * Rewrite bare "Claude Code" self-references in workflow content to
+ * `brandName`, EXCEPT inside `<runtime_compatibility>...</runtime_compatibility>`
+ * blocks, which are left byte-for-byte verbatim. Every other content
+ * transform in a runtime's `.md` converter (tool-name renames, path
+ * rewrites, etc.) is unaffected — only this literal brand-name swap is
+ * protected-region-aware, since only it risks mislabeling a
+ * runtime-comparison table.
+ *
+ * Implementation: SPLIT `content` on the protected-block regex, brand-swap
+ * only the GAP text between (and around) matches, then rejoin gap+block
+ * alternately. No placeholder/sentinel token of any kind is substituted in
+ * — a prior version used a sentinel-token mask/restore, which is exactly the
+ * kind of invisible landmine this rewrite eliminates (a sentinel string, no
+ * matter how obscure, is a theoretical collision risk with real content and
+ * is easy to silently reintroduce in a future edit without it showing in a
+ * diff). Behavior-identical to the removed sentinel-token version — verified
+ * via `npm run gen:golden` producing zero further diff.
+ */
+function applyClaudeCodeBrandSwap(content, brandName) {
+  if (!brandName) return content;
+  let result = '';
+  let lastIndex = 0;
+  RUNTIME_COMPATIBILITY_BLOCK_RE.lastIndex = 0; // reset shared global-regex state before each use
+  let m;
+  while ((m = RUNTIME_COMPATIBILITY_BLOCK_RE.exec(content))) {
+    const gap = content.slice(lastIndex, m.index);
+    result += gap.replace(/\bClaude Code\b/g, brandName);
+    result += m[0]; // protected block, verbatim — never brand-swapped
+    lastIndex = m.index + m[0].length;
+  }
+  result += content.slice(lastIndex).replace(/\bClaude Code\b/g, brandName);
+  return result;
+}
+
 // Tool name mapping from Claude Code to Cursor CLI
 const claudeToCursorTools = {
   Bash: 'Shell',
@@ -2400,8 +2583,9 @@ function convertClaudeToCursorMarkdown(content) {
   // Remove Claude Code-specific bug workarounds before brand replacement
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
   converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  // Replace "Claude Code" brand references with "Cursor"
-  converted = converted.replace(/\bClaude Code\b/g, 'Cursor');
+  // Replace "Claude Code" brand references with "Cursor" — #2284(b): skips
+  // <runtime_compatibility> comparison-table content (protected region).
+  converted = applyClaudeCodeBrandSwap(converted, 'Cursor');
   return converted;
 }
 
@@ -2445,7 +2629,13 @@ function convertClaudeCommandToCursorSkill(content, skillName) {
   const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
   const adapter = getCursorSkillAdapterHeader(skillName);
 
-  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  // #2341: mark user-invocable:false so the skill is NOT shown in Cursor's '/'
+  // menu (it defaults to true). Cursor also writes a commands/ surface (#785),
+  // and surfacing both duplicated every /gsd-* entry. This mirrors the #789
+  // CodeBuddy de-dup: the commands/ surface is the sole '/' entry point; skills
+  // stay model-invocable background knowledge. (user-invocable:false hides from
+  // '/' while keeping model invocation — distinct from disable-model-invocation.)
+  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\nuser-invocable: false\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 /**
@@ -2533,8 +2723,9 @@ function convertClaudeToWindsurfMarkdown(content) {
   // Remove Claude Code-specific bug workarounds before brand replacement
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
   converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  // Replace "Claude Code" brand references with "Windsurf"
-  converted = converted.replace(/\bClaude Code\b/g, 'Windsurf');
+  // Replace "Claude Code" brand references with "Windsurf" — #2284(b): skips
+  // <runtime_compatibility> comparison-table content (protected region).
+  converted = applyClaudeCodeBrandSwap(converted, 'Windsurf');
   return converted;
 }
 
@@ -2668,7 +2859,8 @@ function convertClaudeToTraeMarkdown(content) {
   converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'TRAE_CONFIG_DIR');
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
   converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  converted = converted.replace(/\bClaude Code\b/g, 'Trae');
+  // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
+  converted = applyClaudeCodeBrandSwap(converted, 'Trae');
   return converted;
 }
 
@@ -2740,7 +2932,8 @@ function convertClaudeToCodebuddyMarkdown(content) {
   converted = converted.replace(/\.claude\//g, '.codebuddy/');
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
   converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  converted = converted.replace(/\bClaude Code\b/g, 'CodeBuddy');
+  // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
+  converted = applyClaudeCodeBrandSwap(converted, 'CodeBuddy');
   return converted;
 }
 
@@ -2835,7 +3028,8 @@ function convertClaudeToCliineMarkdown(content) {
   converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'CLINE_CONFIG_DIR');
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
   converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  converted = converted.replace(/\bClaude Code\b/g, 'Cline');
+  // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
+  converted = applyClaudeCodeBrandSwap(converted, 'Cline');
   return converted;
 }
 
@@ -2888,6 +3082,825 @@ function convertClaudeCommandToClineSkill(content, skillName, runtime = null, cm
 
 // ── End Cline converters ─────────────────────────────────────────────────────
 
+// ── Hermes converters (#2284) ────────────────────────────────────────────────
+//
+// Hermes exposes `delegate_task` for subagent dispatch, not the Claude-shaped
+// `Agent(...)` tool the host-neutral `gsd-core/workflows/*.md` corpus assumes.
+// Prior to this fix, the hermes `.md` hook (RUNTIME_CONTENT_DISPATCH.hermes)
+// only brand-swapped "Claude Code" → "Hermes Agent" via
+// hostBehaviors.brandingRewrites, leaving the false "Agent tool IS available"
+// assertion and literal `Agent(...)` call syntax installed verbatim.
+//
+// `projectNamedDispatchToStructuralDelegate` is GENERIC projection machinery:
+// it branches ENTIRELY on the runtime's documentation-sourced
+// `hostIntegration.dispatch` facts (read via `_hostIntegrationDispatch`,
+// capabilities/<runtime>/capability.json — never hardcoded here) and a
+// `toolConfig` that supplies only the target primitive's own vocabulary (its
+// call name + native parameter names — not a capability claim; there is no
+// `dispatch` axis for "the call's own parameter names", so that vocabulary is
+// necessarily supplied by the caller, exactly as every other runtime's
+// converter supplies its own tool-name vocabulary, e.g. Trae's `Shell(`).
+//
+// Hermes-specific facts consumed (capabilities/hermes/capability.json,
+// docs/reference/host-integration-capability-matrix.md:244-249 — UNCHANGED by
+// this fix):
+//   - dispatch.namedDispatch: false — Hermes's delegate_task has no named-
+//     agent lookup ("Subagents are identified only by role ('leaf' or
+//     'orchestrator')"). GSD resolves the referenced gsd-* role itself
+//     (fail-closed against the staged agents/ dir) and embeds the loaded
+//     PROMPT CONTENT into the delegate_task payload.
+//   - dispatch.background: true — `delegate_task(background=true)` "returns a
+//     handle immediately"; Claude's `run_in_background=` maps onto Hermes's
+//     own `background=` parameter, preserving the async-handle / no-busy-poll
+//     / resume-on-completion wording already used throughout these workflows.
+//   - dispatch.subagentToolkit: "read-only" / dispatch.maxDepth: 1 — dispatched
+//     roles never themselves further delegate, so no nested-delegation
+//     instruction is ever emitted toward them.
+
+/**
+ * Resolve the set of gsd-* role-prompt stems actually shipped in this
+ * package's `agents/` directory (the FULL source set, not profile-staged —
+ * `--minimal`/`--profile=core` intentionally excludes many agents from a
+ * given install without those workflows being unreachable, so validating
+ * against the profile-filtered subset would fail every restricted-profile
+ * Hermes install; validating against the shipped source catches genuine
+ * authoring bugs — a stale/typo'd role reference — without that regression).
+ * Returns `null` if the directory cannot be resolved (fail-closed: callers
+ * must refuse to install rather than skip validation).
+ */
+function _resolveAvailableGsdRoles() {
+  try {
+    const agentsDir = path.join(__dirname, '..', 'agents');
+    return new Set(
+      fs.readdirSync(agentsDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => e.name.slice(0, -3)),
+    );
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Fail-closed validation (#2284 AC: "Missing role prompts fail closed" /
+ * "never emit a workflow referencing an unresolvable role"). A single literal
+ * `gsd-*` role value must resolve to a real `agents/<role>.md` file — throws
+ * an explicit Error otherwise, aborting the install (the standard
+ * `copyWithPathReplacement` failure path already used for its own
+ * confinement-violation throws). Called per extracted role value from EVERY
+ * call-syntax form (`subagent_type=`, `subagent_type:`, post-rename
+ * `gsd_role=`) — the check operates on the resolved value, independent of
+ * which source syntax produced it. Non-literal / dynamic expressions (e.g.
+ * `research_hook.ref.agent`) are not quoted strings and are never passed
+ * here; they carry their own runtime resolution + fail-closed instruction via
+ * the injected per-call resolution line.
+ */
+function _assertRoleResolvable(role, availableRoles, runtime, sourceDescription) {
+  if (!availableRoles) {
+    throw new Error(
+      `${runtime} workflow install: could not resolve the shipped agents/ directory to validate named-role ` +
+      'dispatch references — refusing to install (fail-closed, #2284)',
+    );
+  }
+  if (role.startsWith('gsd-') && !availableRoles.has(role)) {
+    throw new Error(
+      `${runtime} workflow install: dispatch references role "${role}" via ${sourceDescription}, but no ` +
+      `matching agents/${role}.md prompt file is shipped — refusing to install a workflow that dispatches ` +
+      'an unresolvable role (fail-closed, #2284)',
+    );
+  }
+}
+
+/**
+ * Segment `text` into 'code' and 'string' runs (recognizes `"..."`, `'...'`,
+ * and Python-style `"""..."""`, with backslash-escaping). Required because
+ * the real corpus embeds unescaped parens inside quoted prompt bodies (e.g.
+ * discuss-phase-assumptions.md's `(e.g., "Technical Approach")` inside a
+ * `"""`-quoted prompt) — naive paren/keyword scanning across raw text would
+ * desync on these. Downstream call-span detection and header-token
+ * extraction operate on a same-length MASK derived from this segmentation
+ * (see `maskStringLiterals`) so string content can never be mistaken for
+ * call structure.
+ */
+function _segmentCodeAndStrings(text) {
+  const segments = [];
+  let i = 0;
+  let segStart = 0;
+  const flushCode = (end) => { if (end > segStart) segments.push({ type: 'code', start: segStart, end }); };
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"' && text[i + 1] === '"' && text[i + 2] === '"') {
+      flushCode(i);
+      const strStart = i;
+      i += 3;
+      while (i < text.length && !(text[i] === '"' && text[i + 1] === '"' && text[i + 2] === '"')) {
+        i += text[i] === '\\' ? 2 : 1;
+      }
+      i = Math.min(i + 3, text.length);
+      segments.push({ type: 'string', start: strStart, end: i, quoteLen: 3 });
+      segStart = i;
+      continue;
+    }
+    // Only `"` is recognized as a single-char string delimiter — NOT `'`.
+    // The corpus is markdown prose, not code: apostrophes are routine English
+    // contractions/possessives ("install's", "don't") and treating them as
+    // string delimiters would swallow everything up to the next unrelated
+    // apostrophe as "inside a string" (verified against the real corpus —
+    // this was a real, disqualifying bug during development of this fix).
+    // Every real call-argument value in the corpus uses `"`/`"""` only.
+    if (ch === '"') {
+      flushCode(i);
+      const strStart = i;
+      i += 1;
+      while (i < text.length && text[i] !== '"') {
+        i += text[i] === '\\' ? 2 : 1;
+      }
+      i = Math.min(i + 1, text.length);
+      segments.push({ type: 'string', start: strStart, end: i, quoteLen: 1 });
+      segStart = i;
+      continue;
+    }
+    i += 1;
+  }
+  flushCode(text.length);
+  return segments;
+}
+
+/**
+ * Same-length mask of `text` with the INTERIOR of every string literal
+ * replaced by a space (newlines preserved, so line-based regexes still work).
+ * The delimiting quote character(s) themselves (`"`, `'`, `"""`) are kept
+ * verbatim so a value-extraction regex like `key\s*[=:]\s*"[^"]*"` still
+ * matches correctly against the mask — only the STRING CONTENT is blanked,
+ * never the quote structure. Positions in the mask line up 1:1 with `text`,
+ * so match indices/offsets found against the mask are valid offsets into the
+ * original.
+ */
+function maskStringLiterals(text) {
+  let mask = '';
+  for (const seg of _segmentCodeAndStrings(text)) {
+    const slice = text.slice(seg.start, seg.end);
+    if (seg.type === 'code') { mask += slice; continue; }
+    const q = seg.quoteLen;
+    if (slice.length <= q) { mask += slice; continue; } // truncated/unterminated — keep verbatim
+    const closeLen = Math.min(q, slice.length - q);
+    const open = slice.slice(0, q);
+    const close = slice.slice(slice.length - closeLen);
+    const interiorLen = slice.length - q - closeLen;
+    const interior = interiorLen > 0 ? slice.slice(q, q + interiorLen) : '';
+    mask += open + interior.replace(/[^\n]/g, ' ') + close;
+  }
+  return mask;
+}
+
+/**
+ * Locate every `<headWord>(` / `<headWord>({` call span in `text`.
+ *
+ * #2284 round-2 CRITICAL fix: this MUST NOT rely on whole-document quote
+ * parity. A markdown workflow file mixes prose, ```bash code fences (full of
+ * their own double-quoted strings), and shell quoting — there is no single
+ * document-wide quote grammar, so a `"`-heavy bash `echo` upstream of a real
+ * call (e.g. code-review.md's fenced `echo "..."` block before its
+ * `Agent(subagent_type="gsd-code-reviewer", ...)` call) can desync a
+ * CUMULATIVE quote-state scan, making the scanner believe the real call's
+ * `Agent(` sits "inside a string" and silently skipping it entirely — the
+ * call then survives completely unnormalized. (Reproduced and root-caused
+ * against the real corpus.)
+ *
+ * Fixed shape: find each `<headWord>(` occurrence via a PLAIN literal-text
+ * search (`indexOf`, immune to any prior document content), then run a
+ * balanced paren-matching scan whose quote-tracking state STARTS FRESH AT
+ * THE HEAD — local to this one call, never inherited from (or able to be
+ * corrupted by) anything earlier in the document. Handles all three real
+ * corpus shapes: multi-line one-key-per-line, single-line object-literal
+ * (`Agent({ ... })`), and single-line compact
+ * (`Agent(subagent_type="x", model="y", prompt="...")`) — including prompt
+ * bodies containing their own unescaped `()`/`{}` (skipped via the SAME
+ * span-local quote tracking, e.g. discuss-phase-assumptions.md's
+ * `"""`-quoted parenthetical prose).
+ *
+ * Returns `[{start, end, hasBraceWrapper}]` — `start`/`end` bound the FULL
+ * call INCLUDING the head word and the closing `)`/`})`.
+ */
+function findDispatchCallSpans(text, headWord) {
+  const spans = [];
+  const headToken = `${headWord}(`;
+  let searchFrom = 0;
+  for (;;) {
+    const start = text.indexOf(headToken, searchFrom);
+    if (start === -1) break;
+    const prevChar = start > 0 ? text[start - 1] : '';
+    if (/[A-Za-z0-9_]/.test(prevChar)) { searchFrom = start + 1; continue; } // word-boundary guard
+
+    let i = start + headToken.length; // just past the '('
+    let j = i;
+    while (j < text.length && /\s/.test(text[j])) j++;
+    const hasBraceWrapper = text[j] === '{';
+
+    // LOCAL scan — quote/paren state is fresh here, never inherited from
+    // anything before `start` in the document.
+    let parenDepth = 1;
+    let inString = null; // null | '"' | 'triple'
+    let end = -1;
+    for (; i < text.length; i++) {
+      const ch = text[i];
+      if (inString) {
+        if (ch === '\\') { i++; continue; }
+        if (inString === 'triple') {
+          if (ch === '"' && text[i + 1] === '"' && text[i + 2] === '"') { inString = null; i += 2; }
+          continue;
+        }
+        if (ch === inString) inString = null;
+        continue;
+      }
+      if (ch === '"' && text[i + 1] === '"' && text[i + 2] === '"') { inString = 'triple'; i += 2; continue; }
+      if (ch === '"') { inString = '"'; continue; }
+      if (ch === '(') { parenDepth++; continue; }
+      if (ch === ')') {
+        parenDepth--;
+        if (parenDepth === 0) { end = i + 1; break; }
+        continue;
+      }
+    }
+    if (end === -1) { searchFrom = start + 1; continue; } // unterminated — skip past, keep scanning
+    spans.push({ start, end, hasBraceWrapper });
+    searchFrom = end;
+  }
+  return spans;
+}
+
+/**
+ * Remove a call argument's `[matchStart, matchEnd)` token from `spanText`,
+ * consuming its surrounding comma/whitespace so no dangling `, ,` or trailing
+ * comment survives. When the argument owns its whole line, the whole line
+ * (including a trailing inline `# comment`) is removed; `consumeLeadingComments`
+ * additionally removes contiguous comment-only lines immediately ABOVE it —
+ * #2284 Finding 5: explanatory prose describing a now-removed conditional
+ * (e.g. execute-phase.md's "# Only include model= when ...") must not survive
+ * describing a branch that no longer exists. Inline (single-line-compact /
+ * object-literal) occurrences instead eat one adjacent comma.
+ */
+function _stripCallArgument(spanText, matchStart, matchEnd, { consumeLeadingComments = false } = {}) {
+  let end = matchEnd;
+  const afterRe = /^[ \t]*,?[ \t]*(#[^\n]*)?\r?\n?/;
+  const afterMatch = afterRe.exec(spanText.slice(end));
+  const hadTrailingComma = !!(afterMatch && /,/.test(afterMatch[0]));
+  if (afterMatch) end += afterMatch[0].length;
+
+  let start = matchStart;
+  const lineStart = spanText.lastIndexOf('\n', start - 1) + 1;
+  const ownLine = /^[ \t]*$/.test(spanText.slice(lineStart, start));
+  if (ownLine) {
+    start = lineStart;
+    if (consumeLeadingComments) {
+      for (;;) {
+        const prevLineStart = start > 0 ? spanText.lastIndexOf('\n', start - 2) + 1 : 0;
+        const prevLine = spanText.slice(prevLineStart, start);
+        if (/^[ \t]*#[^\n]*\r?\n$/.test(prevLine)) {
+          start = prevLineStart;
+          if (prevLineStart === 0) break;
+        } else break;
+      }
+    }
+  } else if (!hadTrailingComma) {
+    // Inline form and this was the LAST arg (no trailing comma) — eat a
+    // leading comma so the previous arg doesn't dangle one.
+    const before = spanText.slice(0, start);
+    const cm = /,[ \t]*$/.exec(before);
+    if (cm) start -= cm[0].length;
+  }
+  return spanText.slice(0, start) + spanText.slice(end);
+}
+
+/**
+ * Replace a named-role argument token's `[matchStart, matchEnd)` span
+ * (`subagent_type=`/`subagent_type:` + its value) with the projected
+ * `gsd_role=` / role-prompt-resolution / structural-role argument group.
+ * Preserves the pretty multi-line one-arg-per-line style when the original
+ * token owned its own line; falls back to an inline, comma-joined group for
+ * the single-line-compact and object-literal forms.
+ */
+function _projectRoleArgument(spanText, matchStart, matchEnd, roleValueExpr, toolConfig, canOrchestrate) {
+  const { namedRoleParam, promptContentParam, structuralRoleParam, leafRoleValue } = toolConfig;
+  const lineStart = spanText.lastIndexOf('\n', matchStart - 1) + 1;
+  const startsOwnLine = /^[ \t]*$/.test(spanText.slice(lineStart, matchStart));
+
+  // Consume an immediately-following separator comma (+ same-line whitespace/
+  // newline) into `end` — never leave it dangling AFTER an injected trailing
+  // `# comment` (a bare `,` after `#...` would sit on the comment's own line,
+  // outside any real argument list).
+  let end = matchEnd;
+  const afterRe = /^[ \t]*,[ \t]*\r?\n?/;
+  const afterMatch = afterRe.exec(spanText.slice(end));
+  const hadTrailingComma = !!afterMatch;
+  if (afterMatch) end += afterMatch[0].length;
+  const ownLine = startsOwnLine && hadTrailingComma && /\n$/.test(afterMatch[0]);
+
+  const promptContentPhrase =
+    `${promptContentParam}=<resolve ${roleValueExpr} against the active install's gsd-* role prompts and load ` +
+    'its contents; FAIL CLOSED with an explicit error if unresolved — never execute the role inline>';
+
+  let replacement;
+  if (ownLine) {
+    const indent = spanText.slice(lineStart, matchStart);
+    const depthNote = canOrchestrate ? '' : '  # nested delegation is unavailable at this dispatch depth/toolkit';
+    replacement =
+      `${namedRoleParam}=${roleValueExpr},\n` +
+      `${indent}${promptContentPhrase},\n` +
+      `${indent}${structuralRoleParam}="${leafRoleValue}",${depthNote}\n`;
+  } else {
+    // Inline forms never carry a trailing `#` comment mid-argument-list (it
+    // would silently "comment out" the remainder of the call), so the
+    // depth/toolkit caveat is only ever emitted in the pretty own-line form.
+    // Re-emit exactly the separator that originally followed this argument
+    // (a comma if more args follow; nothing if it was the last one).
+    replacement =
+      `${namedRoleParam}=${roleValueExpr}, ${promptContentPhrase}, ${structuralRoleParam}="${leafRoleValue}"` +
+      (hadTrailingComma ? ', ' : '');
+  }
+  return spanText.slice(0, matchStart) + replacement + spanText.slice(end);
+}
+
+// Matches a `subagent_type`/`model` argument's key+delimiter+value across all
+// three corpus forms: quoted-string values ("gsd-planner", "{model}") and
+// bare dynamic-expression values (ref.agent, research_hook.ref.agent,
+// executor_model). The captured group is always the value (a suffix of the
+// whole match), so its start offset is `match.index + match[0].length -
+// match[1].length` — avoids needing the regex `d` (indices) flag.
+function _callArgValueRe(key) {
+  return new RegExp(`\\b${key}\\s*[=:]\\s*("(?:[^"\\\\]|\\\\.)*"|[A-Za-z_][\\w.]*)`);
+}
+
+/**
+ * Returns the literal role name from a captured role-argument value EXPR
+ * (e.g. `"gsd-planner"`) — or `null` when it is not a genuine static
+ * literal: a bare dynamic expression (`ref.agent`), OR a quoted value that
+ * still contains `{...}` template interpolation (the corpus's own
+ * placeholder convention, e.g. `model="{researcher_model}"` — and,
+ * critically, `subagent_type: "gsd-{agent}"` in
+ * gsd-core/references/universal-anti-patterns.md, a DOCUMENTATION template
+ * illustrating the naming pattern, never a concrete role to resolve).
+ * Fail-closed validation only ever runs on a genuine static literal; a
+ * template/dynamic value still gets the full role-prompt-resolution
+ * projection treatment (the resolve+fail-closed instruction applies equally
+ * once a template is substituted at runtime) — only the STATIC CHECK is
+ * skipped, never the projection itself.
+ */
+function _literalRoleValue(roleValueExpr) {
+  const m = /^"([^"]*)"$/.exec(roleValueExpr);
+  if (!m) return null;
+  if (/[{}]/.test(m[1])) return null;
+  return m[1];
+}
+
+/**
+ * `maskStringLiterals` PLUS `#`-to-end-of-line comment blanking (comments are
+ * never string literals, so they survive string-masking as literal `#...`
+ * text). Header-token searches (subagent_type/model/run_in_background) must
+ * use THIS mask, not the string-only one — verified necessary against the
+ * real corpus: execute-phase.md's explanatory comment "# Only include
+ * model= when executor_model is..." literally contains the substring
+ * "model= when", which a comment-blind `model` regex mismatches as a real
+ * `model=when` argument, corrupting the comment AND missing the real
+ * `model="{executor_model}"` line beneath it. Scoped to call-span text only
+ * (never the whole document), so markdown `#`/`##` headings elsewhere are
+ * unaffected.
+ */
+function _maskStringsAndComments(text) {
+  return maskStringLiterals(text).replace(/#[^\n]*/g, (m) => ' '.repeat(m.length));
+}
+
+/**
+ * Normalize ONE `Agent(...)`/`Agent({...})` call span (already isolated by
+ * `findDispatchCallSpans`) onto the target's real dispatch primitive. Every
+ * behavioral branch reads `dispatch` (the runtime's sourced
+ * `hostIntegration.dispatch` facts) — none is hardcoded. Handles all three
+ * corpus call-argument shapes uniformly via string-aware token location
+ * (`maskStringLiterals` recomputed after each structural edit, since prior
+ * edits shift offsets).
+ */
+function _normalizeDispatchCallSpan(spanText, hasBraceWrapper, dispatch, toolConfig) {
+  const namedDispatch = dispatch.namedDispatch === true;
+  const backgroundCapable = dispatch.background === true;
+  const canOrchestrate = dispatch.subagentToolkit === 'full'
+    && (dispatch.maxDepth === -1 || (typeof dispatch.maxDepth === 'number' && dispatch.maxDepth > 1));
+  const { toolName, backgroundParam, supportsPerCallModel, availableRoles, runtime } = toolConfig;
+
+  let text = spanText;
+
+  // 1. Named-role argument (subagent_type= / subagent_type:) — only when the
+  //    target has no native named-agent lookup (dispatch.namedDispatch).
+  //    Fail-closed validation runs on the extracted value REGARDLESS of
+  //    which source syntax produced it (#2284 requirement 2).
+  if (!namedDispatch) {
+    const roleRe = _callArgValueRe('subagent_type');
+    const rm = roleRe.exec(_maskStringsAndComments(text));
+    if (rm) {
+      // Read the VALUE from the original (unmasked) text at the matched
+      // offset — `rm[1]` was captured against the mask, whose string
+      // INTERIOR is blanked, so it must never be used as the real value.
+      const roleValueExpr = text.slice(rm.index + rm[0].length - rm[1].length, rm.index + rm[0].length);
+      const literalRole = _literalRoleValue(roleValueExpr);
+      if (literalRole !== null) {
+        _assertRoleResolvable(literalRole, availableRoles, runtime, 'subagent_type');
+      } else if (!availableRoles) {
+        // No literal value to check, but a null availableRoles still means
+        // the shipped agents/ dir couldn't be resolved at all — fail closed
+        // unconditionally rather than silently install an unverifiable call.
+        _assertRoleResolvable('', availableRoles, runtime, 'subagent_type');
+      }
+      text = _projectRoleArgument(text, rm.index, rm.index + rm[0].length, roleValueExpr, toolConfig, canOrchestrate);
+    }
+  }
+
+  // 2. Per-call model argument (model= / model:) — stripped entirely when the
+  //    target has no per-call model-selection parameter (there is no
+  //    `dispatch` axis for this — it is inherent tool vocabulary, like the
+  //    parameter names themselves). Also removes now-dead explanatory
+  //    comment lines directly above a `model=` line that owns its own line
+  //    (#2284 Finding 5).
+  if (!supportsPerCallModel) {
+    const modelRe = _callArgValueRe('model');
+    const mm = modelRe.exec(_maskStringsAndComments(text));
+    if (mm) {
+      text = _stripCallArgument(text, mm.index, mm.index + mm[0].length, { consumeLeadingComments: true });
+    }
+  }
+
+  // 3. Background-dispatch flag (run_in_background= / run_in_background:) —
+  //    maps onto the target's own background parameter ONLY when documented
+  //    to support it; otherwise stripped rather than forwarding a parameter
+  //    the primitive doesn't accept.
+  {
+    const bgRe = /\brun_in_background\s*[=:]\s*(?:true|false)/;
+    const bm = bgRe.exec(_maskStringsAndComments(text));
+    if (bm) {
+      if (backgroundCapable) {
+        const matched = text.slice(bm.index, bm.index + bm[0].length);
+        const replaced = matched.replace(/^run_in_background(\s*[=:]\s*)/, `${backgroundParam}$1`);
+        text = text.slice(0, bm.index) + replaced + text.slice(bm.index + bm[0].length);
+      } else {
+        text = _stripCallArgument(text, bm.index, bm.index + bm[0].length);
+      }
+    }
+  }
+
+  // 4. Call-syntax head rename + object-literal brace stripping. Hermes's
+  //    delegate_task is a flat kwarg call — `Agent({...})`'s wrapper braces
+  //    are dropped rather than carried through, so every projected call ends
+  //    up in the same flat shape regardless of source syntax.
+  text = text.replace(/^Agent\(/, `${toolName}(`);
+  if (hasBraceWrapper) {
+    const openMask = maskStringLiterals(text);
+    const braceOpenIdx = openMask.indexOf('{');
+    if (braceOpenIdx !== -1) text = text.slice(0, braceOpenIdx) + text.slice(braceOpenIdx + 1);
+    const closeMask = maskStringLiterals(text);
+    const braceCloseIdx = closeMask.lastIndexOf('}');
+    if (braceCloseIdx !== -1) text = text.slice(0, braceCloseIdx) + text.slice(braceCloseIdx + 1);
+  }
+
+  return text;
+}
+
+/**
+ * Blank the interior (and delimiters) of every string literal inside
+ * `spanText` to spaces — same length, newlines preserved — using a fresh,
+ * LOCAL quote-tracking scan that starts at `spanText[0]` with NO inherited
+ * state. This is deliberately the SAME state-machine shape as the
+ * `inString`/`\\`/triple-quote handling inside `findDispatchCallSpans`
+ * (double-quoted and `"""`-triple-quoted, backslash-escape aware) — reused
+ * here so a call span's quoted argument VALUES (documentation prose, prompt
+ * bodies) never masquerade as real call syntax, without EVER falling back to
+ * a whole-document cumulative quote-parity mask (the round-2 defect
+ * documented on `findDispatchCallSpans` above).
+ */
+function _blankStringLiteralInteriors(spanText) {
+  let out = '';
+  let inString = null; // null | '"' | 'triple'
+  for (let i = 0; i < spanText.length; i++) {
+    const ch = spanText[i];
+    if (inString) {
+      if (ch === '\\') {
+        out += ' ';
+        i++;
+        if (i < spanText.length) out += (spanText[i] === '\n') ? '\n' : ' ';
+        continue;
+      }
+      if (inString === 'triple') {
+        if (ch === '"' && spanText[i + 1] === '"' && spanText[i + 2] === '"') {
+          inString = null;
+          out += '   ';
+          i += 2;
+          continue;
+        }
+        out += (ch === '\n') ? '\n' : ' ';
+        continue;
+      }
+      if (ch === inString) { inString = null; out += ' '; continue; }
+      out += (ch === '\n') ? '\n' : ' ';
+      continue;
+    }
+    if (ch === '"' && spanText[i + 1] === '"' && spanText[i + 2] === '"') {
+      inString = 'triple';
+      out += '   ';
+      i += 2;
+      continue;
+    }
+    if (ch === '"') { inString = '"'; out += ' '; continue; }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * Quote-aware view of `content` for the completeness checks below: for every
+ * REAL call span located via `findDispatchCallSpans` (once per head word in
+ * `headWords`), the string-literal ARGUMENT VALUES inside that span are
+ * blanked via `_blankStringLiteralInteriors`; the call's own head word and
+ * bare (unquoted) argument tokens are left untouched. `headWords` is
+ * processed in order and each pass re-scans the PROGRESSIVELY-masked string
+ * — `toolName` first, then `'Agent'` — so a spurious `Agent(` that
+ * `findDispatchCallSpans('Agent')` would otherwise "find" purely because it
+ * sits inside an outer call's quoted string (e.g. a `description="...Agent()
+ * ...subagent_type=x"` argument value) has ALREADY been blanked away by the
+ * outer `toolName` pass by the time the `'Agent'` pass runs, so it is never
+ * mistaken for a real, independent call. A genuinely real (unquoted) `Agent(`
+ * — including one nested as a raw, un-renamed argument value — survives every
+ * pass and remains visible to the caller's regex checks.
+ */
+function _maskQuotedRegionsWithinCallSpans(content, headWords) {
+  let masked = content;
+  for (const headWord of headWords) {
+    const spans = findDispatchCallSpans(masked, headWord);
+    for (let i = spans.length - 1; i >= 0; i--) {
+      const { start, end } = spans[i];
+      const maskedSpan = _blankStringLiteralInteriors(masked.slice(start, end));
+      masked = masked.slice(0, start) + maskedSpan + masked.slice(end);
+    }
+  }
+  return masked;
+}
+
+/**
+ * Post-projection guard (#2284 requirement 3 — belt-and-suspenders): after
+ * projection, assert the corpus form the projection could not anticipate
+ * never silently ships. Throws an explicit install error (fail-LOUD) rather
+ * than let an unprojected/incompletely-projected dispatch call install.
+ *
+ * #2284 round-2 CRITICAL fix: this is an INDEPENDENT check — it does NOT use
+ * `maskStringLiterals` over the whole document (the round-1 primitive whose
+ * cumulative, document-wide quote-parity tracking was the root cause of the
+ * round-2 defect: a `"`-heavy bash fence upstream of a real call desynced
+ * quote state and made `findDispatchCallSpans` blind to that call, shipping
+ * a Frankenstein `Agent(gsd_role="...", model="...")` with no detection).
+ *
+ * #2284 round-3 fix: a BLUNT, mask-free literal check over the whole
+ * document (round-2's fix) over-throws — it cannot tell a real residual
+ * `Agent(`/`subagent_type` call from the SAME text appearing INSIDE a quoted
+ * string (documentation/prompt prose, e.g. `description="...Agent()..."`).
+ * The completeness checks (residual `subagent_type` / literal `Agent(`) now
+ * run against `_maskQuotedRegionsWithinCallSpans` — quote-aware, but scoped
+ * strictly to already-correctly-bounded, per-occurrence-LOCAL call spans
+ * (never a whole-document cumulative mask), so a real Frankenstein call
+ * (unquoted, real call syntax) still fires while a same-text mention genuinely
+ * inside a quoted string does not.
+ *
+ * The completeness checks also only apply when `namedDispatch` is false: when
+ * `dispatch.namedDispatch === true`, `_normalizeDispatchCallSpan` step 1
+ * INTENTIONALLY leaves `subagent_type` unprojected (the target primitive
+ * resolves named agents itself) — a residual `subagent_type` in that case is
+ * the correct, intended output, not a defect. (The call HEAD is still renamed
+ * unconditionally regardless of `namedDispatch` — see step 4 there — so a
+ * literal `Agent(` residual is gated the same way purely for symmetry with
+ * the dispatch-facts-driven contract; it is never actually left unrenamed by
+ * the projection in practice.)
+ *
+ * The model-leak check is unaffected by either fix above — it is orthogonal
+ * to `namedDispatch` (gated only by `supportsPerCallModel`) and already
+ * bounds each real call via the independently-fixed, per-occurrence-local,
+ * non-cumulative `findDispatchCallSpans`, then does a raw substring check
+ * within that bound.
+ */
+function _assertProjectionComplete(content, toolConfig, namedDispatch = false) {
+  const { toolName, runtime, supportsPerCallModel } = toolConfig;
+
+  if (!namedDispatch) {
+    const quoteAware = _maskQuotedRegionsWithinCallSpans(content, [toolName, 'Agent']);
+    if (/\bsubagent_type\s*[=:]/.test(quoteAware)) {
+      throw new Error(
+        `${runtime} workflow install: projection left a residual subagent_type reference — refusing to install ` +
+        '(fail-closed post-projection guard, #2284)',
+      );
+    }
+    if (/\bAgent\(/.test(quoteAware)) {
+      throw new Error(
+        `${runtime} workflow install: projection left literal Agent( call syntax — refusing to install ` +
+        '(fail-closed post-projection guard, #2284)',
+      );
+    }
+  }
+
+  if (!supportsPerCallModel) {
+    for (const span of findDispatchCallSpans(content, toolName)) {
+      const rawSpanText = content.slice(span.start, span.end);
+      if (/\bmodel\s*[=:]/.test(rawSpanText)) {
+        throw new Error(
+          `${runtime} workflow install: projection left a leaked model= argument inside a ${toolName}(...) call ` +
+          '— refusing to install (fail-closed post-projection guard, #2284)',
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Project host-neutral `Agent(...)` named-subagent dispatch prose onto a
+ * target runtime's real dispatch primitive. See the file-header comment above
+ * for the governing rule: every behavioral branch reads `dispatch` (the
+ * runtime's sourced `hostIntegration.dispatch` facts) — none is a hardcoded
+ * assumption about a specific runtime. Handles all three real corpus call
+ * forms (multi-line one-key-per-line, single-line object-literal, single-line
+ * compact) via string-aware call-span detection rather than three independent
+ * line-anchored regexes, and closes with a post-projection guard that fails
+ * loud on any form it did not anticipate (#2284).
+ *
+ * @param {string} content
+ * @param {{namedDispatch?: boolean, nested?: boolean, maxDepth?: number, background?: boolean, backgroundDispatch?: boolean, subagentToolkit?: string}} dispatch
+ * @param {{toolName: string, namedRoleParam: string, promptContentParam: string, structuralRoleParam: string, leafRoleValue: string, backgroundParam: string, supportsPerCallModel: boolean, availableRoles: Set<string>|null, runtime: string}} toolConfig
+ */
+function projectNamedDispatchToStructuralDelegate(content, dispatch, toolConfig) {
+  const d = dispatch || {};
+  const namedDispatch = d.namedDispatch === true;
+  const backgroundCapable = d.background === true;
+  const { toolName, promptContentParam } = toolConfig;
+
+  let converted = content;
+
+  // 1. The "Agent tool IS available" contract assertion (currently unique to
+  //    plan-phase.md, matched generically in case of future reuse elsewhere).
+  const assertionRe = /The Agent tool IS available in a top-level ([^\n]+?) session\.\s+Always spawn\s+([\s\S]*?)\s+as separate Agent\(\) calls\./;
+  converted = converted.replace(assertionRe, (_m, sessionName, roster) => {
+    const rosterFlat = roster.replace(/\s+/g, ' ').trim();
+    if (namedDispatch) {
+      return `The \`${toolName}\` tool IS available in a top-level ${sessionName} session. Always dispatch ${rosterFlat} as separate \`${toolName}()\` calls.`;
+    }
+    return (
+      `${sessionName} has no \`Agent\` tool. It exposes \`${toolName}\`, which dispatches by structural role — ` +
+      'it has no concept of a named subagent identity. GSD projects each named gsd-* role onto this primitive ' +
+      `itself: resolve the role's prompt file from the active install, load its contents, and embed them in the ` +
+      `\`${toolName}\` payload via \`${promptContentParam}\` as the dispatched task's operating instructions. ` +
+      'FAIL CLOSED — surface an explicit error and stop — if a referenced role prompt cannot be resolved; never ' +
+      `execute the role inline as a substitute. In a top-level ${sessionName} session, always dispatch ` +
+      `${rosterFlat} as separate \`${toolName}\` calls.`
+    );
+  });
+
+  // 1b. Dispatch-depth-availability prose immediately adjacent to a renamed
+  //     `Agent()` mention in the SAME sentence (plan-review-convergence.md
+  //     ~lines 108, 347, 355) — a bare "Agent" left un-renamed right next to
+  //     the projection's own `Agent()`→`${toolName}()` rename produced
+  //     self-contradictory installed text (e.g. "...delegate_task(...)...
+  //     with Agent available..."). Narrowly scoped to the EXACT known
+  //     phrases the projection itself creates the inconsistency beside —
+  //     never a broad bare-word `Agent` rename, which would corrupt
+  //     legitimate `Agent`-adjacent prose elsewhere in the corpus (role
+  //     names, "Agent Brief", agent-file references).
+  converted = converted.replace(
+    /\borchestrator runs at depth 0 with Agent available\b/g,
+    `orchestrator runs at depth 0 with ${toolName} available`,
+  );
+  converted = converted.replace(
+    /\(bug #936: depth-1 Agent has no Agent tool\)/g,
+    `(bug #936: depth-1 ${toolName} has no nested ${toolName})`,
+  );
+
+  // 2. Per-call model-selection prose ("Model resolution:" paragraph,
+  //    execute-phase.md) + inline backtick-quoted model-mention prose
+  //    examples (not live call sites) — only rewritten when the target
+  //    primitive has no per-call model parameter at all.
+  if (!toolConfig.supportsPerCallModel) {
+    const modelResolutionRe = /\*\*Model resolution:\*\* If `executor_model` is `"inherit"`, omit the `model=` parameter from all `Agent\(\)` calls — do NOT pass `model="inherit"` to Agent\. Omitting the `model=` parameter causes [^.]+\. Only set `model=` when `executor_model` is an explicit model name \(e\.g\., `"claude-sonnet-5"`, `"claude-opus-4-8"`\)\./;
+    converted = converted.replace(
+      modelResolutionRe,
+      `**Model resolution:** \`${toolName}\` has no per-call model-selection parameter — every dispatched role ` +
+      `always inherits the host session's active model. Never pass \`model=\` to \`${toolName}\`; drop the ` +
+      '`executor_model` value entirely for this runtime.',
+    );
+    converted = converted.replace(/`model="[^"`\n]*"`,?\s*(?:and\s+)?/g, '');
+  }
+
+  // 3. Background-dispatch PROSE mentions outside any real call span (e.g.
+  //    execute-phase.md:595,600 — `run_in_background: true` inline
+  //    documentation, not a call argument) — #2284 Finding 3. Only rewritten
+  //    when the target is documented to support background dispatch (a
+  //    prose mention of an unsupported capability would be equally
+  //    misleading as a real leaked argument).
+  if (backgroundCapable) {
+    converted = converted.replace(
+      /\brun_in_background(\s*[=:]\s*(?:true|false))/g,
+      `${toolConfig.backgroundParam}$1`,
+    );
+  }
+
+  // 4. Call-span-based normalization — the core of the fix. Every
+  //    `Agent(...)`/`Agent({...})` occurrence (all three corpus forms) is
+  //    located via string-aware balanced paren/brace matching, then
+  //    normalized as a unit; spans are rebuilt right-to-left so earlier
+  //    offsets stay valid while later ones are rewritten.
+  const spans = findDispatchCallSpans(converted, 'Agent');
+  for (let i = spans.length - 1; i >= 0; i--) {
+    const { start, end, hasBraceWrapper } = spans[i];
+    const rebuilt = _normalizeDispatchCallSpan(converted.slice(start, end), hasBraceWrapper, d, toolConfig);
+    converted = converted.slice(0, start) + rebuilt + converted.slice(end);
+  }
+
+  // 5. "Agent tool" capability mentions (conditions gating parallel vs.
+  //    sequential dispatch, e.g. map-codebase.md) → the real target primitive
+  //    name, which resolves these conditions accurately since it IS a real,
+  //    always-available dispatch primitive for this target.
+  converted = converted.replace(/\bAgent tool\b/g, toolName);
+
+  // 5b. Catch-all: a `subagent_type` mention that is NOT part of any real
+  //     `Agent(...)` call span (e.g. map-codebase.md's inline documentation
+  //     prose ``Use Agent tool with `subagent_type="X"`, ...`` — disconnected
+  //     example syntax, not a live call). Renamed for the same accuracy the
+  //     real calls get; a literal quoted role value is still fail-closed
+  //     validated even though there is no call structure to inject
+  //     role-prompt/fail-closed guidance INTO.
+  if (!namedDispatch) {
+    converted = converted.replace(
+      /\bsubagent_type(\s*[=:]\s*"[^"]*")/g,
+      (_m, rest) => {
+        const literalRole = _literalRoleValue(rest.replace(/^\s*[=:]\s*/, ''));
+        if (literalRole !== null) {
+          _assertRoleResolvable(literalRole, toolConfig.availableRoles, toolConfig.runtime, 'subagent_type (prose mention)');
+        }
+        return `${toolConfig.namedRoleParam}${rest}`;
+      },
+    );
+    converted = converted.replace(/\bsubagent_type(\s*[=:])/g, `${toolConfig.namedRoleParam}$1`);
+  }
+
+  // 5c. Safety net (#2284 requirement 2): the PRIMARY mechanism for
+  //     eliminating literal `Agent(` syntax is complete span detection (step
+  //     4) — this unconditional final rename exists only so that even a call
+  //     span detection somehow misses at least loses its `Agent(` head
+  //     rather than shipping the literal Claude-shaped tool name verbatim.
+  //     A call caught only by this safety net is still INCOMPLETELY
+  //     normalized (no role/model handling) and gets caught by the
+  //     independent post-projection guard below via its OTHER invariants
+  //     (residual subagent_type / leaked model=), which this safety net does
+  //     not touch — the install still fails closed for a missed span.
+  converted = converted.replace(/\bAgent\(/g, `${toolName}(`);
+
+  // 6. Post-projection guard (#2284 requirement 3): fail loud, never ship
+  //    silently, on any residual/leaked form the projection above did not
+  //    anticipate. `namedDispatch` gates the completeness checks — a
+  //    residual subagent_type is INTENTIONAL, not a defect, when the target
+  //    resolves named agents itself (see `_assertProjectionComplete`).
+  _assertProjectionComplete(converted, toolConfig, namedDispatch);
+
+  return converted;
+}
+
+const HERMES_DISPATCH_TOOL_CONFIG = Object.freeze({
+  toolName: 'delegate_task',
+  namedRoleParam: 'gsd_role',
+  promptContentParam: 'gsd_role_prompt',
+  structuralRoleParam: 'role',
+  leafRoleValue: 'leaf',
+  backgroundParam: 'background',
+  supportsPerCallModel: false,
+});
+
+/**
+ * Hermes `.md` content converter (#2284): brand-swap (unchanged behavior,
+ * descriptor-driven per `hostBehaviors.brandingRewrites`) followed by the
+ * generic named-dispatch → `delegate_task` projection above, driven by
+ * `capabilities/hermes/capability.json`'s `hostIntegration.dispatch` (read
+ * via `_hostIntegrationDispatch`, values UNCHANGED by this fix — they are
+ * already documentation-sourced and correct).
+ */
+function convertClaudeToHermesMarkdown(content, ctx) {
+  const runtime = (ctx && ctx.runtime) || 'hermes';
+  const b = _hostBehaviors(runtime).brandingRewrites;
+  let converted = content;
+  if (b) {
+    converted = converted.replace(/CLAUDE\.md/g, b['CLAUDE.md']);
+    // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
+    converted = applyClaudeCodeBrandSwap(converted, b['Claude Code']);
+    converted = converted.replace(/\.claude\//g, b['.claude/']);
+  }
+  const dispatch = _hostIntegrationDispatch(runtime);
+  const toolConfig = Object.assign({}, HERMES_DISPATCH_TOOL_CONFIG, {
+    availableRoles: _resolveAvailableGsdRoles(),
+    runtime,
+  });
+  return projectNamedDispatchToStructuralDelegate(converted, dispatch, toolConfig);
+}
+
+// ── End Hermes converters ────────────────────────────────────────────────────
+
 function convertSlashCommandsToCodexSkillMentions(content) {
   // Colon-style /gsd: never appears as a filesystem path segment, so no boundary guard is needed (unlike the hyphen-style below).
   let converted = content.replace(/\/gsd:([a-z0-9-]+)/gi, (_, commandName) => {
@@ -3006,10 +4019,14 @@ Typed mapping (agent_type-capable schema only):
   inherited, or unsupported values; do not invent one-off effort literals in
   workflow prose.
 - \`fork_context: false\` by default — GSD agents load their own context via \`<files_to_read>\` blocks
-- \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct Codex mapping.
-  Codex \`spawn_agent\` does not create or bind a git worktree automatically.
-  Workflows that require this isolation must fail closed or use an explicit
-  manual worktree protocol before spawning (#3360).
+- \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct \`spawn_agent\` mapping,
+  but Codex declares \`dispatch.isolation: orchestrator-worktree\` (#2584). Codex
+  \`spawn_agent\` still does not create or bind a git worktree; instead GSD itself
+  creates the worktree and process-spawns the executor into it with
+  \`codex exec --cd <dir>\`, performing every git operation on the executor's behalf
+  (its \`workspace-write\` sandbox makes \`.git\` read-only). Workflows must therefore
+  never fabricate a manual worktree protocol — route through the negotiated
+  isolation adapter, which still fails closed for hosts declaring \`none\` (#3360).
 
 Generic-agent workaround (multi_agent_v1 schema — NO agent_type field):
 When only the generic \`multi_agent_v1\` schema is available, typed GSD agent dispatch
@@ -3089,6 +4106,36 @@ purpose: ${toSingleLine(description)}
   return `${cleanFrontmatter}\n\n${roleHeader}\n${body}`;
 }
 
+/**
+ * #2310 — True if `model` is an Anthropic-flavored value that must never appear as a
+ * Codex agent `.toml` `model`. Two forms: (a) a bare Claude Agent-tool tier alias
+ * (opus/sonnet/haiku/fable — the canonical CLAUDE_AGENT_ALIASES, imported from
+ * src/model-resolver.cts so it can't diverge); (b) any Claude model id in any provider
+ * namespacing — `claude-*`, `anthropic/claude-*`, `us.anthropic.claude-*` (the forms the
+ * catalog assigns to opencode/hermes/kilo, reachable on a Codex .toml via the runtime-
+ * resolver path). No OpenAI/Codex model id contains "claude", so a case-insensitive
+ * substring test is a safe, exhaustive guard for (b). Codex/ChatGPT rejects all of these.
+ */
+function _isAnthropicFlavoredModel(model) {
+  return typeof model === 'string' && (CLAUDE_AGENT_ALIASES.has(model) || model.toLowerCase().includes('claude'));
+}
+
+// #2310 — dedupe stderr warnings so repeated agent emits don't spam (mirrors the
+// #2041/#1133 model-resolver warn-dedupe). Value is length-capped so an oversized
+// or secret-shaped override cannot leak in full to logs.
+const _codexModelOverrideDroppedWarned = new Set();
+function _warnCodexModelOverrideDropped(agentName, value) {
+  const key = `${agentName}::${value}`;
+  if (_codexModelOverrideDroppedWarned.has(key)) return;
+  _codexModelOverrideDroppedWarned.add(key);
+  const safe = String(value).length > 64 ? `${String(value).slice(0, 64)}…` : String(value);
+  process.stderr.write(
+    `gsd: warning — Codex agent "${agentName}" model "${safe}" is not a valid Codex model ` +
+    `(Anthropic alias/id); dropping it so Codex uses a valid default. ` +
+    `Set runtime:"codex" or pin a gpt-* model to route it.\n`,
+  );
+}
+
 /**
  * Generate a per-agent .toml config file for Codex.
  * Sets required agent metadata, sandbox_mode, and developer_instructions
@@ -3122,21 +4169,43 @@ function generateCodexAgentToml(agentName, agentContent, modelOverrides = null,
   // model_overrides is respected on Codex (which uses static TOML, not inline
   // Task() model parameters). See #2256.
   // Precedence: per-agent model_overrides > runtime-aware tier resolution (#2517).
-  const modelOverride = modelOverrides?.[resolvedName] || modelOverrides?.[agentName];
-  let hasPinnedModel = false;
-  if (modelOverride) {
-    lines.push(`model = ${JSON.stringify(modelOverride)}`);
-    hasPinnedModel = true;
-  } else if (runtimeResolver) {
+  // #2310 — a Codex .toml `model` MUST be a real Codex/OpenAI model id. Codex is a
+  // passive/session-only model host (ADR-1239): GSD cannot reliably route per-agent
+  // tiers, and a bare GSD/Claude tier alias (opus/sonnet/haiku/fable) or a claude-*
+  // id 400s on a ChatGPT-account Codex ("The 'sonnet' model is not supported when
+  // using Codex with a ChatGPT account"). So: embed ONLY an explicit real-Codex
+  // model pin from model_overrides; omit anything Anthropic-flavored so the agent
+  // inherits the always-available session model. (Removing the runtime-resolver
+  // per-tier embedding below is the ADR-2310 passive-posture epic.)
+  const rawModelOverride = modelOverrides?.[resolvedName] || modelOverrides?.[agentName];
+  let pinnedModel = null;
+  if (rawModelOverride) {
+    if (typeof rawModelOverride === 'string' && rawModelOverride && !_isAnthropicFlavoredModel(rawModelOverride)) {
+      pinnedModel = rawModelOverride;   // explicit real-Codex model pin → embed verbatim (#2256)
+    } else {
+      _warnCodexModelOverrideDropped(resolvedName, rawModelOverride);   // alias/claude-* → omit
+    }
+  }
+  if (!pinnedModel && runtimeResolver) {
     // #2517 — runtime-aware tier resolution. Embeds Codex-native model + reasoning_effort
     // from RUNTIME_PROFILE_MAP / model_profile_overrides for the configured tier.
+    // (Superseded on the default path by the ADR-2310 passive-posture epic.)
     const entry = runtimeResolver.resolve(resolvedName) || runtimeResolver.resolve(agentName);
-    if (entry?.model) {
-      lines.push(`model = ${JSON.stringify(entry.model)}`);
-      hasPinnedModel = true;
-      // model is resolved here; reasoning_effort from catalog tier is REPLACED by the
-      // unified effort resolver below (#443). Do NOT emit entry.reasoning_effort here.
-    }
+    if (entry?.model) pinnedModel = entry.model;
+  }
+  // #2310 — final safety gate: never emit an Anthropic-flavored model into a Codex
+  // .toml, even from the runtime-resolver path (e.g. a defaults.json runtime that
+  // does not match the codex install target).
+  if (pinnedModel && _isAnthropicFlavoredModel(pinnedModel)) {
+    _warnCodexModelOverrideDropped(resolvedName, pinnedModel);
+    pinnedModel = null;
+  }
+  let hasPinnedModel = false;
+  if (pinnedModel) {
+    lines.push(`model = ${JSON.stringify(pinnedModel)}`);
+    hasPinnedModel = true;
+    // model is resolved here; reasoning_effort from catalog tier is REPLACED by the
+    // unified effort resolver below (#443). Do NOT emit entry.reasoning_effort here.
   }
 
   // #443 — Unified effort for Codex .toml. Uses the same config-driven precedence chain
@@ -3364,14 +4433,26 @@ function _resolveMovedSkillsOldDir(runtime, targetDir, scope) {
 
 /**
  * Generate the GSD config block for Codex config.toml.
- * @param {Array<{name: string, description: string}>} agents
- */
-function generateCodexConfigBlock(agents, targetDir) {
-  // Use absolute paths when targetDir is provided — Codex ≥0.116 requires
-  // AbsolutePathBuf for config_file and cannot resolve relative paths.
-  const agentsPrefix = targetDir
-    ? path.join(targetDir, 'agents').replace(/\\/g, '/')
-    : 'agents';
+ *
+ * #2406 — standalone per-agent TOMLs (written by installCodexConfig to
+ * `$CODEX_HOME/agents/<name>.toml`) are auto-discovered by Codex and are the
+ * SOLE canonical registration source for each role. This block therefore no
+ * longer emits `[agents.<name>]` role tables that point `config_file` back at
+ * those same standalone TOMLs — that was a second, redundant declaration of
+ * the same role in one config layer, and Codex logged "Ignoring malformed
+ * agent role definition: duplicate agent role name" once per agent as a
+ * result. Only the bare `[agents]` dispatch-tuning scalar table is emitted
+ * here; role name/description/model/reasoning-effort/sandbox settings remain
+ * fully discoverable through the standalone TOML alone.
+ * @param {Array<{name: string, description: string}>} _agents unused — kept
+ *   in the signature for call-site compatibility (installCodexConfig and
+ *   existing tests still pass it positionally); per-agent role tables are no
+ *   longer generated from it.
+ * @param {string} [_targetDir] unused — the standalone-TOML `config_file`
+ *   path it used to resolve is no longer emitted here; kept for the same
+ *   call-site-compatibility reason as `_agents`.
+ */
+function generateCodexConfigBlock(_agents, _targetDir) {
   const lines = [
     GSD_CODEX_MARKER,
     '',
@@ -3380,24 +4461,12 @@ 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.
+  // `[agents]` scalar table is validated by validateCodexConfigSchema, which
+  // permits a known-scalar-only `[agents]`.
   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
-    // "invalid type: sequence, expected struct AgentsToml in `agents`".
-    lines.push(`[agents.${name}]`);
-    lines.push(`description = ${JSON.stringify(description)}`);
-    lines.push(`config_file = "${agentsPrefix}/${name}.toml"`);
-    lines.push('');
-  }
-
   return lines.join('\n');
 }
 
@@ -5922,12 +6991,14 @@ function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-san
   // Symlink-escape guard (parity with _copyStaged / copyWithPathReplacement): the
   // lexical gate above does not resolve symlinks, so a pre-existing config.toml or
   // agents/ symlink could redirect writes outside targetDir. Reject those.
+  // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
+  const symlinkOptIn = isSymlinkedDestOptIn();
   if (
-    hasExistingSymlinkBetween(resolvedTargetRoot, configPath) ||
-    hasExistingSymlinkBetween(resolvedTargetRoot, path.resolve(agentsTomlDir))
+    hasExistingSymlinkBetween(resolvedTargetRoot, configPath, { allowOptInFollow: symlinkOptIn }) ||
+    hasExistingSymlinkBetween(resolvedTargetRoot, path.resolve(agentsTomlDir), { allowOptInFollow: symlinkOptIn })
   ) {
     throw new Error(
-      `installCodexConfig: a Codex config path under "${targetDir}" contains a symlink escaping the install root — refusing to write`,
+      `installCodexConfig: a Codex config path under "${targetDir}" contains a symlink the install root does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`,
     );
   }
   fs.mkdirSync(agentsTomlDir, { recursive: true });
@@ -5978,9 +7049,9 @@ function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-san
     // `name` containing path separators must not escape agents/ (which would let
     // it clobber config.toml or write elsewhere under the configHome).
     const agentTomlPath = assertDestWithinConfigHome(agentsTomlDir, `${name}.toml`);
-    if (hasExistingSymlinkBetween(resolvedTargetRoot, agentTomlPath)) {
+    if (hasExistingSymlinkBetween(resolvedTargetRoot, agentTomlPath, { allowOptInFollow: symlinkOptIn })) {
       throw new Error(
-        `installCodexConfig: agent toml path "${agentTomlPath}" contains a symlink escaping the install root — refusing to write`,
+        `installCodexConfig: agent toml path "${agentTomlPath}" contains a symlink the install root does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`,
       );
     }
     fs.writeFileSync(agentTomlPath, tomlContent);
@@ -6582,7 +7653,8 @@ const RUNTIME_CONTENT_DISPATCH = {
       const b = _hostBehaviors(ctx.runtime).brandingRewrites;
       if (b) {
         content = content.replace(/CLAUDE\.md/g, b['CLAUDE.md']);
-        content = content.replace(/\bClaude Code\b/g, b['Claude Code']);
+        // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
+        content = applyClaudeCodeBrandSwap(content, b['Claude Code']);
         content = content.replace(/\.claude\//g, b['.claude/']);
       }
       return content;
@@ -6599,16 +7671,13 @@ const RUNTIME_CONTENT_DISPATCH = {
     },
   },
   hermes: {
-    md: (content, ctx) => {
-      // Guarded (post-review #2092): see qwen entry above.
-      const b = _hostBehaviors(ctx.runtime).brandingRewrites;
-      if (b) {
-        content = content.replace(/CLAUDE\.md/g, b['CLAUDE.md']);
-        content = content.replace(/\bClaude Code\b/g, b['Claude Code']);
-        content = content.replace(/\.claude\//g, b['.claude/']);
-      }
-      return content;
-    },
+    // #2284: brand-swap alone left the false "Agent tool IS available"
+    // assertion + literal `Agent(...)` call syntax installed verbatim — see
+    // convertClaudeToHermesMarkdown / projectNamedDispatchToStructuralDelegate
+    // above (the Hermes converters section) for the full named-dispatch →
+    // `delegate_task` projection, driven by capabilities/hermes/capability.json's
+    // hostIntegration.dispatch facts.
+    md: (content, ctx) => convertClaudeToHermesMarkdown(content, ctx),
     js: (content, ctx) => {
       const b = _hostBehaviors(ctx.runtime).brandingRewrites;
       if (b) {
@@ -6645,9 +7714,10 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
   }
   const resolvedConfinementRoot = path.resolve(confinementRoot);
   const resolvedDestDir = assertDestWithinConfigHome(confinementRoot, destDir);
-  if (hasExistingSymlinkBetween(resolvedConfinementRoot, resolvedDestDir)) {
+  // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
+  if (hasExistingSymlinkBetween(resolvedConfinementRoot, resolvedDestDir, { allowOptInFollow: isSymlinkedDestOptIn() })) {
     throw new Error(
-      `copyWithPathReplacement: destDir "${destDir}" contains a symlink escaping the install root "${confinementRoot}" — refusing to write`,
+      `copyWithPathReplacement: destDir "${destDir}" contains a symlink the install root "${confinementRoot}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`,
     );
   }
   // Use the validated absolute path for all writes below so the gate validates
@@ -7431,6 +8501,17 @@ function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
         console.log(`  ${green}✓${reset} Removed ${removedLibFiles} hooks/lib/ helper(s)`);
       }
     }
+
+    // #2717: remove the CommonJS marker GSD wrote into hooks/ for runtimes that
+    // stage .js hooks via dedicated paths (cursor/windsurf/codex) — but ONLY if
+    // it still carries GSD's exact content (a user-authored package.json is
+    // never deleted). Safe no-op for runtimes whose marker lives at the config
+    // root (the shared-bundle path) or that never received one.
+    try {
+      if (hooksSurface.removeCommonJsMarkerIfGsdOwned(hooksDir)) {
+        console.log(`  ${green}✓${reset} Removed GSD hooks/package.json (CommonJS marker)`);
+      }
+    } catch { /* best-effort */ }
   }
 
   // 4z. Remove the native plugin adapter (#1914, extended to Kilo by #2093).
@@ -7591,8 +8672,11 @@ function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
       let permissionsModified = false;
       if (Array.isArray(settings.permissions.allow)) {
         const before = settings.permissions.allow.length;
+        // #2278 — filter against the union of the current allow-rule forms
+        // AND the retired legacy forms, so uninstall still cleans up
+        // pre-fix installs that still carry the stale `Write(...)` entries.
         settings.permissions.allow = settings.permissions.allow.filter(
-          (e) => !GSD_CLAUDE_ALLOW_PERMISSIONS.includes(e)
+          (e) => !GSD_CLAUDE_ALLOW_PERMISSIONS.includes(e) && !GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS.includes(e)
         );
         if (settings.permissions.allow.length !== before) {
           permissionsModified = true;
@@ -8303,7 +9387,7 @@ function resolveInstallRelativePath(baseDir, relPath) {
   if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
     return null;
   }
-  if (hasExistingSymlinkBetween(root, fullPath)) {
+  if (hasExistingSymlinkBetween(root, fullPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
     return null;
   }
   return { relPath: normalized, fullPath };
@@ -8377,9 +9461,14 @@ function writeManifest(configDir, runtime = DEFAULT_RUNTIME, options = {}) {
     }
   }
   if (_hostBehaviors(runtime).flatCommandDir && fs.existsSync(opencodeCommandDir)) {
+    // #2329: derive the manifest key prefix from the SAME descriptor value used
+    // to compute opencodeCommandDir above, instead of a separately-hardcoded
+    // literal — a divergence here would silently break the manifest even after
+    // the destSubpath descriptor is corrected (Generative Fix Divergence guard).
+    const flatCommandDirPrefix = _hostBehaviors(runtime).flatCommandDir || 'command';
     for (const file of fs.readdirSync(opencodeCommandDir)) {
       if (file.startsWith('gsd-') && file.endsWith('.md')) {
-        manifest.files['command/' + file] = fileHash(path.join(opencodeCommandDir, file));
+        manifest.files[flatCommandDirPrefix + '/' + file] = fileHash(path.join(opencodeCommandDir, file));
       }
     }
   }
@@ -8974,14 +10063,24 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   const _effectiveInstallMode = _isCoreProfileAlias ? 'minimal' : 'full';
   // Load the manifest and compute resolved profile for named profiles.
   // For --minimal/core: use an empty manifest (core profile has no transitive
-  // deps) to produce a resolvedProfile with the core skill set.  Registry IS
-  // consulted so tier:core capability skills are included when registered.
+  // deps) to produce a resolvedProfile with the core skill set.  For core/
+  // standard profiles, resolveProfile's `registry` arg IS consulted (via
+  // _capabilitySkillsForMode) so tier:core/tier:standard capability skills are
+  // unioned in when registered. #2322 correction: for the DEFAULT `full`
+  // profile, resolveProfile short-circuits to the `{skills:'*'}` sentinel
+  // BEFORE ever reading `registry` (there is nothing to union — '*' already
+  // means "everything"), so the registry consultation that matters for `full`
+  // happens LATER, at staging time (stageSkillsForRuntimeAsSkills's '*'
+  // fill-in, resolveRuntimeArtifactLayout's `capabilityRegistry` param below) —
+  // not here. `_installedCapabilityRegistry` (not the frozen `_capabilityRegistry`)
+  // is passed so an INSTALLED third-party capability (not just a first-party
+  // one) is honored on every profile, `full` included (#2322 blocker 2).
   const _commandsDir = path.join(src, 'commands', 'gsd');
   const _skillsManifest = _isCoreProfileAlias ? new Map() : loadSkillsManifest(_commandsDir);
   const _resolvedProfile = resolveProfile({
     modes: [_activeProfileName],
     manifest: _skillsManifest,
-    registry: _capabilityRegistry,
+    registry: _installedCapabilityRegistry,
   });
   // Unified staging function: all profiles use stageSkillsForProfile with the
   // registry-aware _resolvedProfile (ADR-857 phase 4c cutover).
@@ -9318,6 +10417,45 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     return Array.isArray(scopeLayout) && scopeLayout.length > 0;
   })();
 
+  // #2624: write the .gsd-source marker. Extracted from its former late position so it can be
+  // called BEFORE staging reads the marker (see the call site below). Scoped to the Claude-global
+  // layout (issue #1477) — the only install path that ships the skills layout without a
+  // commands/gsd source tree, so findInstallSourceRoot's walk-up has nothing to find and
+  // /gsd-surface (list/status) throws without it. Points at the package's own commands/gsd
+  // source. Guarded on source presence so a half-published package never writes a dangling
+  // marker. Write failure is non-fatal (install proceeds; warn so /gsd-surface breakage is
+  // diagnosable) — the same contract the late write had.
+  function _writeGsdSourceMarker(runtime, targetDir, src, isGlobal) {
+    if (_hostBehaviors(runtime).sourceMarkerFile && isGlobal) {
+      const gsdSourceCommands = path.join(src, 'commands', 'gsd');
+      if (fs.existsSync(gsdSourceCommands)) {
+        try {
+          // 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
+          // still leaves /gsd-surface broken at runtime — warn so it's diagnosable.
+          console.warn(`  ${yellow}!${reset} Could not write .gsd-source marker (${err.message}); /gsd-surface list/status may fail`);
+        }
+      }
+    }
+  }
+
+  // #2624: write the .gsd-source marker BEFORE any staging reads it. The marker write
+  // formerly lived AFTER staging; on an upgrade the marker still held the PREVIOUS
+  // install's source path (e.g. an npx per-version cache dir that still exists on disk),
+  // so findInstallSourceRoot(configDir) — called inside installRuntimeArtifacts below —
+  // returned the stale path and every converted skill was generated from the OLD version's
+  // commands/gsd, silently installing prior-version content with a self-consistent manifest
+  // hash. Writing first closes the read-before-write hole for every findInstallSourceRoot
+  // consumer (skills, commands, /gsd-surface, capability-state). Placed here (before the
+  // _isSkillsRuntime branch) so it runs for every Claude-global install, matching the
+  // original write's sourceMarkerFile && isGlobal guard exactly.
+  _writeGsdSourceMarker(runtime, targetDir, src, isGlobal);
+
   if (_isSkillsRuntime) {
     // Layout-driven install for skills-based runtimes (full and minimal modes)
     const scope = isGlobal ? 'global' : 'local';
@@ -9341,7 +10479,10 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
         resolveAttribution: getCommitAttribution,
       });
     } else {
-      installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile, getCommitAttribution);
+      // #2322: fallback path (adapter unavailable) — thread the composed
+      // registry too, so this path stages third-party capability skills
+      // identically to the primary adapter path above.
+      installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile, getCommitAttribution, _installedCapabilityRegistry);
     }
 
     // #1326 — Codex only: remove stale agents/openai.yaml sidecars from managed
@@ -9500,7 +10641,8 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   } else if (_hostBehaviors(runtime).pluginOnlyInstall) {
     // pi (ADR-1239 / #2102 Stage 1): plugin-only install — pi's /gsd command is
     // registered programmatically by the native extension (pi/gsd.cjs →
-    // extensions/gsd.cjs, staged separately below) and dispatches in-process
+    // extensions/gsd.js, staged separately below; the dest suffix must be
+    // .ts/.js or pi's auto-discovery skips it silently — #2470) and dispatches in-process
     // through the embedded gsd-core command-routing hub. pi has no host-read
     // markdown surface (unlike Claude/OpenCode/etc., which scan commands/ or
     // command/ directories), so writing flat gsd-<cmd>.md files here would be
@@ -9602,35 +10744,11 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     failures.push('gsd-core');
   }
 
-  // Write the .gsd-source marker so runtime source resolution succeeds at
-  // runtime (#1477). The Claude-global skills layout ships gsd-core/{bin,
-  // contexts,references,templates,workflows} but NOT the commands/gsd source
-  // tree, and _runLegacyUninstallCleanup actively removes any commands/gsd/
-  // for that scope — so findInstallSourceRoot's walk-up has nothing to find
-  // and /gsd-surface (list/status) throws. This is the writer half of the
-  // marker that runtime-artifact-layout.cjs's finders already read (the reader
-  // landed in #1476). It points at the package's own commands/gsd source.
-  // Scoped to the Claude-global layout (issue #1477) — the only install path
-  // that ships the skills layout without a commands/gsd source tree; every
-  // 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 (_hostBehaviors(runtime).sourceMarkerFile && isGlobal) {
-    const gsdSourceCommands = path.join(src, 'commands', 'gsd');
-    if (fs.existsSync(gsdSourceCommands)) {
-      try {
-        // 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
-        // still leaves /gsd-surface broken at runtime — warn so it's diagnosable.
-        console.warn(`  ${yellow}!${reset} Could not write .gsd-source marker (${err.message}); /gsd-surface list/status may fail`);
-      }
-    }
-  }
+  // #2624: the .gsd-source marker is now written by _writeGsdSourceMarker()
+  // BEFORE staging reads it (see the early call above the _isSkillsRuntime
+  // block). The former write lived here — AFTER staging — which on an upgrade
+  // let staging read a stale prior-version marker and silently install
+  // old-version skill content. Moved up; this site intentionally left empty.
 
   // #1629 critical fix: Windsurf workflow wrappers (convertClaudeCommandToWindsurfWorkflow)
   // delegate to command bodies at <targetDir>/gsd-core/commands/gsd/${stem}.md via a
@@ -9910,6 +11028,22 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     failures.push('VERSION');
   }
 
+  // #2297: write a per-install runtime marker co-located with VERSION at
+  // <install>/gsd-core/.gsd-runtime. It gives resolveModelInternal a reliable
+  // "which runtime owns THIS install" signal in a no-project session (config.runtime
+  // is null and GSD_RUNTIME is not exported), so the shared ~/.gsd/defaults.json
+  // resolve_model_ids:"omit" policy (written below for non-alias runtimes only)
+  // applies ONLY when a non-alias runtime is actually resolving — a Claude session
+  // reads its own marker and keeps its tier aliases instead of inheriting another
+  // runtime's install-order-dependent "omit". See src/model-resolver.cts.
+  const runtimeMarkerDest = path.join(targetDir, 'gsd-core', '.gsd-runtime');
+  fs.writeFileSync(runtimeMarkerDest, `${runtime}\n`);
+  if (verifyFileInstalled(runtimeMarkerDest, '.gsd-runtime')) {
+    console.log(`  ${green}✓${reset} Wrote runtime marker (.gsd-runtime: ${runtime})`);
+  } else {
+    failures.push('.gsd-runtime');
+  }
+
   // Reusable: copy hooks/dist/ + hooks/lib/ into destRootDir, writing the
   // CommonJS package.json marker alongside them. Used below for the generic
   // configDir install path (guarded by hostBehaviors.skipSharedHooksInstall),
@@ -10023,13 +11157,15 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     }
 
     // Gate hooks/lib/ install on the same set of runtimes that receive hooks/.
-    // Codex/Copilot/Cursor/Windsurf/Trae/Cline/Kilo do not use the shared
+    // Codex/Copilot/Cursor/Windsurf/Trae/Cline do not use the shared
     // hooks/lib/ helpers (Cursor uses standalone .js hook scripts registered
     // via hooks.json — gated descriptor-driven via
-    // hostBehaviors.skipSharedHooksInstall, #2089; Cline likewise #2090; Kilo
-    // likewise #2093; Trae likewise #2094; Codex uses hooks.json directly;
-    // the others skip hooks entirely); Kilo and ZCode also skip hooks entirely
-    // (hooksSurface:'none' with no plugin surface — #1821). None of the
+    // hostBehaviors.skipSharedHooksInstall, #2089; Cline likewise #2090;
+    // Trae likewise #2094; Codex uses hooks.json directly;
+    // the others skip hooks entirely); ZCode also skips hooks entirely
+    // (hooksSurface:'none' with no plugin surface — #1821). Kilo is NOT
+    // excluded since #2305: its native plugin adapter (#2093) spawns the
+    // staged hooks/*.js scripts, same as OpenCode. 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. (Gating lives at the call sites
@@ -10045,18 +11181,21 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     return hooksOk;
   }
 
-  // #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.
+  // #1821: ZCode declares hooksSurface:'none' AND has no plugin surface,
+  // so the staged hook scripts are dead weight for it — excluded 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.
+  // them and the CommonJS package.json marker written below. Kilo is the same
+  // shape since #2093 (a nativePlugin spawning the staged hooks), so it must
+  // NOT skip either — declaring skipSharedHooksInstall:true alongside a
+  // nativePlugin left every guard the plugin spawns a silent no-op (#2305).
   // #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.
-  // #2093: Kilo's exclusion is likewise descriptor-driven (kilo declares
-  // skipSharedHooksInstall:true) — the redundant `&& !isKilo` was removed.
+  // #2093/#2305: Kilo's former exclusion (descriptor-driven via
+  // skipSharedHooksInstall:true) was removed in #2305 — see above.
   // #2094: Trae's exclusion is likewise descriptor-driven (trae declares
   // skipSharedHooksInstall:true) — the redundant `&& !isTrae` was removed.
   // #2101: ZCode's exclusion is likewise descriptor-driven (zcode declares
@@ -10275,7 +11414,15 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     throw _earlyInstallErr;
   }
 
-  if (plan.installSurface === 'codex-toml' && !isMinimalMode(_effectiveInstallMode)) {
+  // #2695: this branch runs for BOTH `core` (minimal) and `full` profiles.
+  // Hooks are lightweight infrastructure (update-check + context monitor), not the
+  // "full agent surface" that `core` deliberately omits. The config.toml / agent
+  // generation below is still gated by its own inner `!isMinimalMode` guard, so
+  // `core` enters the branch to receive the hook-file copy + hooks.json wiring but
+  // does NOT get agent roles generated. Before #2695 the outer `!isMinimalMode`
+  // here skipped the whole branch for `core`, so the registered parent hook pointed
+  // at a worker/registry the same installer never delivered.
+  if (plan.installSurface === 'codex-toml') {
     // Capture pre-install snapshots before ANY GSD mutation
     // (#2760 fix 3). On post-write schema-validation failure OR any throw
     // during the mutation sequence (write failure, merge throw, etc.) we
@@ -10458,9 +11605,18 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
 
     // Copy only the hook files that Codex actually registers via its hook configuration (#2153).
     // #772: added gsd-context-monitor.js for the new SubagentStart/Stop/PostToolUse events.
+    // #2695: the parent gsd-check-update.js spawn()s gsd-check-update-worker.js, which
+    //   require()s managed-hooks-registry.cjs for MANAGED_HOOKS — so all four must be
+    //   installed/refreshed together for every profile, or Codex is wired to a dependency
+    //   chain the same installer never delivers.
     // We deliberately do *not* copy gsd-graphify-update.sh or hooks/lib/ for Codex
     // in this change (graphify auto-update support for Codex is out of scope for #3579).
-    const CODEX_HOOKS_TO_COPY = ['gsd-check-update.js', 'gsd-context-monitor.js'];
+    const CODEX_HOOKS_TO_COPY = [
+      'gsd-check-update.js',
+      'gsd-check-update-worker.js',
+      'managed-hooks-registry.cjs',
+      'gsd-context-monitor.js',
+    ];
     const codexHooksSrc = path.join(src, 'hooks', 'dist');
     if (fs.existsSync(codexHooksSrc)) {
       const codexHooksDest = path.join(targetDir, 'hooks');
@@ -10490,9 +11646,28 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
           fs.writeFileSync(destFile, content);
           try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
+        } else {
+          // #2695: raw byte-for-byte copy for allowlisted artifacts that carry
+          // no {{GSD_VERSION}} placeholder and no runtime path token (e.g.
+          // managed-hooks-registry.cjs, whose only `.claude` mention is inside a
+          // doc comment). Version/path transforms would be a no-op at best and a
+          // surprise at worst; the issue requires the registry copied verbatim.
+          fs.copyFileSync(srcFile, destFile);
+          try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
         }
       }
       console.log(`  ${green}✓${reset} Installed hooks (Codex)`);
+      // #2717: write the CommonJS marker into hooks/ alongside the staged .js
+      // scripts. Codex is excluded from installSharedHooksBundle by the
+      // !isCodex gate, so it never received the marker the shared-bundle path
+      // writes for the other runtimes. Without it, a ~/.codex/package.json
+      // declaring {"type":"module"} makes Node load gsd-check-update.js /
+      // gsd-context-monitor.js as ESM and their require() calls fail silently.
+      // Reuses the same helper the Cursor/Windsurf writers call so the marker
+      // content + user-file-preservation contract is identical everywhere.
+      if (hooksSurface.ensureCommonJsMarker(codexHooksDest)) {
+        console.log(`  ${green}✓${reset} Wrote hooks/package.json (CommonJS mode)`);
+      }
     }
 
     // Add Codex hooks (SessionStart for update checking) — requires codex_hooks feature flag
@@ -11221,6 +12396,19 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
         fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
         console.log(`  ${green}✓${reset} Set resolve_model_ids: "omit" in ~/.gsd/defaults.json`);
       }
+
+      // #2395: also persist `runtime: <runtime>` for non-Claude runtimes, so
+      // resolveRuntime() (precedence: GSD_RUNTIME env > config.runtime > 'claude')
+      // resolves to the install's actual runtime identity out of the box — without
+      // this, agent_runtime and every runtime-branded slash hint falls through to
+      // the hard-coded 'claude' default. Mirrors the resolve_model_ids write above:
+      // honor an explicit pre-existing value (any string), only default-populating
+      // when absent. Claude is the resolveRuntime() fallback, so it needs no write.
+      if (defaults.runtime === undefined || defaults.runtime === null || defaults.runtime === '') {
+        defaults.runtime = runtime;
+        fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
+        console.log(`  ${green}✓${reset} Set runtime: "${runtime}" in ~/.gsd/defaults.json`);
+      }
     } catch (e) {
       console.log(`  ${yellow}⚠${reset} Could not write ~/.gsd/defaults.json: ${e.message}`);
     }
@@ -11331,16 +12519,17 @@ const runtimeMap = {
   '8': 'cursor',
   '9': 'hermes',
   '10': 'kimi',
-  '11': 'kilo',
-  '12': 'opencode',
-  '13': 'pi',
-  '14': 'qwen',
-  '15': 'trae',
-  '16': 'windsurf',
-  '17': 'zcode'
+  '11': 'kimi-code',
+  '12': 'kilo',
+  '13': 'opencode',
+  '14': 'pi',
+  '15': 'qwen',
+  '16': 'trae',
+  '17': 'windsurf',
+  '18': 'zcode'
 };
-const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kilo', 'opencode', 'pi', 'qwen', 'trae', 'windsurf', 'zcode'];
-const ALL_RUNTIMES_OPTION = '18';
+const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kimi-code', 'kilo', 'opencode', 'pi', 'qwen', 'trae', 'windsurf', 'zcode'];
+const ALL_RUNTIMES_OPTION = '19';
 
 /**
  * Build the runtime-selection prompt text shown by the interactive installer.
@@ -11358,14 +12547,15 @@ function buildRuntimePromptText() {
   ${cyan}8${reset}) Cursor       ${dim}(~/.cursor)${reset}
   ${cyan}9${reset}) Hermes Agent ${dim}(~/.hermes)${reset}
   ${cyan}10${reset}) Kimi         ${dim}(~/.config/agents, then ~/.agents if existing)${reset}
-  ${cyan}11${reset}) Kilo         ${dim}(~/.config/kilo)${reset}
-  ${cyan}12${reset}) OpenCode     ${dim}(~/.config/opencode)${reset}
-  ${cyan}13${reset}) pi           ${dim}(~/.pi/agent)${reset}
-  ${cyan}14${reset}) Qwen Code    ${dim}(~/.qwen)${reset}
-  ${cyan}15${reset}) Trae         ${dim}(~/.trae)${reset}
-  ${cyan}16${reset}) Windsurf     ${dim}(~/.codeium/windsurf)${reset}
-  ${cyan}17${reset}) ZCode        ${dim}(~/.zcode)${reset}
-  ${cyan}18${reset}) All
+  ${cyan}11${reset}) Kimi Code    ${dim}(~/.kimi-code)${reset}
+  ${cyan}12${reset}) Kilo         ${dim}(~/.config/kilo)${reset}
+  ${cyan}13${reset}) OpenCode     ${dim}(~/.config/opencode)${reset}
+  ${cyan}14${reset}) pi           ${dim}(~/.pi/agent)${reset}
+  ${cyan}15${reset}) Qwen Code    ${dim}(~/.qwen)${reset}
+  ${cyan}16${reset}) Trae         ${dim}(~/.trae)${reset}
+  ${cyan}17${reset}) Windsurf     ${dim}(~/.codeium/windsurf)${reset}
+  ${cyan}18${reset}) ZCode        ${dim}(~/.zcode)${reset}
+  ${cyan}19${reset}) All
 
   ${dim}Select multiple: 1,2,6 or 1 2 6${reset}
 `;
@@ -11376,7 +12566,7 @@ function buildRuntimePromptText() {
  * Pure function — exported so tests can verify split/dedupe/fallback behavior.
  *  - Accepts comma- and/or whitespace-separated choices
  *  - Deduplicates while preserving order
- *  - Maps option 16 ("All") to every runtime
+ *  - Maps option 19 ("All") to every runtime
  *  - Falls back to ['claude'] when nothing valid is selected
  */
 function parseRuntimeInput(answer) {
@@ -12157,6 +13347,7 @@ module.exports = {
     // #768 — Claude Code permissions pre-population
     mergeClaudePermissions,
     GSD_CLAUDE_ALLOW_PERMISSIONS,
+    GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS,
     GSD_CLAUDE_DENY_PERMISSIONS,
     GSD_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,
@@ -12206,6 +13397,18 @@ module.exports = {
     convertClaudeToCliineMarkdown,
     convertClaudeCommandToClineSkill,
     convertClaudeAgentToClineAgent,
+    // #2284(b) — cross-cutting branding protected-region helper
+    applyClaudeCodeBrandSwap,
+    // #2284 — Hermes named-dispatch → delegate_task projection
+    convertClaudeToHermesMarkdown,
+    projectNamedDispatchToStructuralDelegate,
+    _hostIntegrationDispatch,
+    _resolveAvailableGsdRoles,
+    HERMES_DISPATCH_TOOL_CONFIG,
+    maskStringLiterals,
+    findDispatchCallSpans,
+    _assertProjectionComplete,
+    _normalizeDispatchCallSpan,
     buildClineRulesBody,
     buildClineAgentsMdBody,
     buildClinePreToolUseHook,