@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -31,11 +31,14 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // `require('../../../package.json')`. That require ran at module load on every
 // gsd-tools invocation (this module sits in the gsd-tools loader chain) and
 // threw `Cannot find module '../../../package.json'` on runtimes whose root has
-// no package.json — notably Codex, where the installer omits the synthetic root
-// package.json — taking the entire CLI down before it did anything. And even
-// where it resolved (Claude's synthetic `{"type":"commonjs"}`), there is no
-// `version` field, so the single consumer below already emitted
-// `version: undefined`. Resolve lazily and defensively instead:
+// no package.json — originally just Codex, where the installer never wrote the
+// synthetic root package.json; since #2544 that is true of EVERY runtime, as
+// GSD's markers moved into `hooks/` and the native plugin dir and the config
+// root is no longer written at all — taking the entire CLI down before it did
+// anything. And even where it used to resolve (the synthetic
+// `{"type":"commonjs"}`), there is no `version` field, so the single consumer
+// below already emitted `version: undefined`. Resolve lazily and defensively
+// instead:
 //   1. Installed trees carry <root>/gsd-core/VERSION (written by the installer);
 //      this module lives at <root>/gsd-core/bin/lib, so VERSION is two dirs up.
 //   2. The source / npm-package tree has no gsd-core/VERSION but carries a real
@@ -365,7 +368,14 @@ function skillFrontmatterName(skillDirName) {
     return skillDirName;
 }
 function normalizeClaudeSkillEffort(effort) {
-    return effort === 'xhigh' ? 'max' : effort;
+    // #3039: `max` is rejected by Anthropic models when extended thinking is
+    // disabled (400: output_config.effort 'max' is not supported when thinking
+    // is disabled). The frontmatter is static at install time and the installer
+    // cannot know whether thinking will be on or off at invocation. `high` is the
+    // maximum value that works in both states on all supported models.
+    if (effort === 'xhigh' || effort === 'max')
+        return 'high';
+    return effort;
 }
 /**
  * Qwen Code skills accept an optional numeric `priority` frontmatter field.
@@ -848,8 +858,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;
 }
 function getCursorSkillAdapterHeader(skillName) {
@@ -890,39 +901,41 @@ function convertClaudeCommandToCursorSkill(content, skillName) {
     description = toSingleLine(description);
     const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
     const adapter = getCursorSkillAdapterHeader(skillName);
-    // #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()}`;
-}
-/**
- * Convert a Claude Code command to a Cursor 1.6 slash command (#785).
- *
- * Cursor slash commands live in `.cursor/commands/<name>.md` and are
- * plain markdown — no YAML frontmatter, no adapter header. The filename
- * becomes the command name (e.g. `gsd-help.md` → `/gsd-help`).
- *
- * Applies the same `convertClaudeToCursorMarkdown` transforms as the skill
- * converter (tool renames, brand substitution, slash-command normalisation),
- * then strips the YAML frontmatter block so only the prose body remains.
- *
- * @param {string} content   raw Claude Code command markdown (may have frontmatter)
- * @param {string} _commandName  the target command name (unused; present for
- *   API symmetry with other converters so the runtime-artifact-layout stage
- *   function can call it uniformly)
- * @returns {string} plain markdown body, no frontmatter
- */
-function convertClaudeCommandToCursorCommand(content, _commandName) {
-    const converted = convertClaudeToCursorMarkdown(content);
-    const { body } = extractFrontmatterAndBody(converted);
-    return body.trimStart();
+    // Cursor skills are both slash-invocable and model-invocable. Do not emit the
+    // unsupported `user-invocable` field: it is ignored by Cursor and previously
+    // hid the real cause of duplicate entries, the parallel commands/ surface
+    // retired in #2644.
+    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 // --- Windsurf converters ---
 // Windsurf uses a tool set similar to Cursor.
 // Config lives in .windsurf/ (local) and ~/.codeium/windsurf/ (global).
+// #2931: ported from bin/install.js's local Windsurf converter copy, which had
+// picked up the #2284(b) protected-region fix that this exported source never
+// received. Binding bin/install.js's Windsurf family to these exports (see
+// tests/install-runtime-artifacts.test.cjs reference-identity assertions)
+// without this would have silently regressed live installs: `Claude Code`
+// mentions inside a `<runtime_compatibility>` comparison table would start
+// getting brand-swapped again. 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 involved.
+const RUNTIME_COMPATIBILITY_BLOCK_RE = /<runtime_compatibility>[\s\S]*?<\/runtime_compatibility>/g;
+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;
+}
 function convertSlashCommandsToWindsurfSkillMentions(content) {
     // Keep leading "/" for slash commands; only normalize gsd: -> gsd-.
     return content.replace(/gsd:/gi, 'gsd-');
@@ -953,8 +966,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;
 }
 function getWindsurfSkillAdapterHeader(skillName) {
@@ -993,10 +1007,46 @@ function convertClaudeCommandToWindsurfSkill(content, skillName) {
         }
     }
     description = toSingleLine(description);
-    const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
+    // #2931: code-point-safe truncation (see truncateWindsurfWorkflowDescription
+    // below) — a raw UTF-16 `slice(0, 177)` can bisect a surrogate pair and
+    // emit a lone surrogate on re-encode. Same exact bounds as before (>180
+    // chars -> first 177 code points + '...'), just harmonized with the
+    // sibling Windsurf workflow converter's helper instead of duplicating the
+    // surrogate-splitting idiom here.
+    const shortDescription = truncateWindsurfWorkflowDescription(description);
     const adapter = getWindsurfSkillAdapterHeader(skillName);
     return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
+// #2931: cap on the Windsurf workflow's only unbounded input (the frontmatter
+// `description`). Shared (not just mirrored) by convertClaudeCommandToWindsurfSkill
+// above — both converters call truncateWindsurfWorkflowDescription below so
+// there is exactly one code-point-safe truncation idiom, not two.
+const WINDSURF_WORKFLOW_DESCRIPTION_MAX = 180;
+function truncateWindsurfWorkflowDescription(description) {
+    // Multi-byte safe: slice by Unicode code points (`Array.from`), never by
+    // raw UTF-16 index — an index-based slice can bisect a surrogate pair and
+    // emit a lone surrogate / U+FFFD on re-encode. See #2931.
+    const codePoints = Array.from(description);
+    if (codePoints.length <= WINDSURF_WORKFLOW_DESCRIPTION_MAX)
+        return description;
+    return `${codePoints.slice(0, WINDSURF_WORKFLOW_DESCRIPTION_MAX - 3).join('')}...`;
+}
+// #2931: SEPARATE size control from the #1615 security regex below — do not
+// fold the two together or make either conditional on the other. The #1615
+// regex constrains commandName's CHARACTER CLASS but not its LENGTH, and
+// commandName is interpolated into the emitted template three times (the
+// `# <commandName>` heading, the `@.../<stem>.md` @-reference target, and the
+// trailing "after /<commandName>" mention) — so an unbounded commandName
+// reopens the byte-cap hole the removed 12000-byte throw used to close
+// (verified: commandName length 246 -> 900 bytes, 5000 -> 15,162 bytes,
+// 20000 -> 60,162 bytes — all silently over the old 12000 cap). THROW rather
+// than truncate: a truncated commandName would silently point the workflow's
+// `@~/.claude/gsd-core/commands/gsd/<stem>.md` reference at a file that does
+// not exist (see DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED) — a name
+// too long to represent is a genuine error, not something to degrade. 128 is
+// deliberately generous: the longest real shipped command name is
+// `gsd-plan-review-convergence` at 27 characters.
+const WINDSURF_COMMAND_NAME_MAX = 128;
 function convertClaudeCommandToWindsurfWorkflow(content, commandName) {
     // #1615 security: commandName flows unsanitized into a markdown body that
     // Windsurf loads as an LLM-readable workflow. Validate at entry to prevent
@@ -1005,21 +1055,43 @@ function convertClaudeCommandToWindsurfWorkflow(content, commandName) {
     // Pattern: optional gsd- prefix + lowercase alphanumeric + dashes; rejects
     // everything else. See DEFECT.PROMPT-INJECTION-SCAN-COLLISION and the
     // PR #1622 security review.
+    // #2931: this is a SECURITY control, not a size control — do not weaken,
+    // reorder, or make it conditional on the description-truncation logic
+    // added below. Keep the two concerns independent even though both happen
+    // to run in this function.
     if (typeof commandName !== 'string' || !/^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(commandName)) {
         const preview = typeof commandName === 'string' ? JSON.stringify(commandName.slice(0, 60)) : String(commandName);
         throw new Error(`convertClaudeCommandToWindsurfWorkflow: rejected commandName ${preview}; ` +
             'must match /^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ (no slashes, backslashes, spaces, dots, trailing dash, or control chars — prevents prompt injection and path-component injection into the workflow body)');
     }
+    // #2931: SEPARATE size control — see WINDSURF_COMMAND_NAME_MAX above for
+    // why this exists and why it throws instead of truncating. Kept as an
+    // independent check from the #1615 regex above (not folded into it, not
+    // conditional on it).
+    if (commandName.length > WINDSURF_COMMAND_NAME_MAX) {
+        const preview = JSON.stringify(commandName.slice(0, 60));
+        throw new Error(`convertClaudeCommandToWindsurfWorkflow: commandName too long (${commandName.length} chars, ` +
+            `preview ${preview}...); max ${WINDSURF_COMMAND_NAME_MAX} chars (see WINDSURF_COMMAND_NAME_MAX)`);
+    }
     const converted = convertClaudeToWindsurfMarkdown(content);
     const { frontmatter } = extractFrontmatterAndBody(converted);
-    const description = frontmatter ? extractFrontmatterField(frontmatter, 'description') : '';
+    const rawDescription = frontmatter ? extractFrontmatterField(frontmatter, 'description') : '';
+    // #2931: a whitespace-only description is truthy (`description || fallback`
+    // would keep it) but toSingleLine() collapses it to ''. Treat it as absent
+    // so the fallback is used instead of emitting a blank line.
+    const singleLineDescription = rawDescription ? toSingleLine(rawDescription) : '';
+    const effectiveDescription = truncateWindsurfWorkflowDescription(singleLineDescription || `Run ${commandName}.`);
     const stem = commandName.startsWith('gsd-') ? commandName.slice(4) : commandName;
-    const workflow = `# ${commandName}\n\n${toSingleLine(description || `Run ${commandName}.`)}\n\nRead and execute the GSD command at @~/.claude/gsd-core/commands/gsd/${stem}.md end-to-end. Treat the user's message after /${commandName} as the command arguments.`;
-    const byteLength = Buffer.byteLength(workflow, 'utf8');
-    if (byteLength > 12000) {
-        throw new Error(`Windsurf workflow ${commandName} exceeds 12000 bytes (${byteLength}); extract references before installing`);
-    }
-    return workflow;
+    // #2931: total emission size is bounded by (fixed template text) +
+    // (3 x WINDSURF_COMMAND_NAME_MAX, one per commandName/stem interpolation
+    // above) + (WINDSURF_WORKFLOW_DESCRIPTION_MAX Unicode code points, up to 4
+    // UTF-8 bytes each). Both inputs are validated/truncated above — commandName
+    // is length-capped-and-thrown by WINDSURF_COMMAND_NAME_MAX, description is
+    // truncated by truncateWindsurfWorkflowDescription — so this bound holds by
+    // construction, not by measurement. The 12000-byte figure itself lives in
+    // exactly one place — the cap table in tests/helpers/emitted-caps.cjs —
+    // this comment only justifies why the actual emitted size stays under it.
+    return `# ${commandName}\n\n${effectiveDescription}\n\nRead and execute the GSD command at @~/.claude/gsd-core/commands/gsd/${stem}.md end-to-end. Treat the user's message after /${commandName} as the command arguments.`;
 }
 // --- Augment converters ---
 // Augment uses a tool set similar to Cursor/Windsurf.
@@ -1047,8 +1119,9 @@ function convertClaudeToAugmentMarkdown(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 "Augment"
-    converted = converted.replace(/\bClaude Code\b/g, 'Augment');
+    // Replace "Claude Code" brand references with "Augment" — #2284(b): skips
+    // <runtime_compatibility> comparison-table content (protected region).
+    converted = applyClaudeCodeBrandSwap(converted, 'Augment');
     return converted;
 }
 // #2097 (ADR-1239): command-body converters selected by descriptor
@@ -1111,10 +1184,55 @@ function convertClaudeToTraeMarkdown(content) {
     // Replace general-purpose subagent type with Trae's equivalent "general_purpose_task"
     converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="general_purpose_task"');
     converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
-    converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.trae/rules/`');
-    converted = converted.replace(/\.\/CLAUDE\.md/g, '.trae/rules/');
-    converted = converted.replace(/`CLAUDE\.md`/g, '`.trae/rules/`');
-    converted = converted.replace(/\bCLAUDE\.md\b/g, '.trae/rules/');
+    // #2658: full-path forms (with a leading dot-claude-slash prefix) MUST be
+    // replaced before the bare Claude-instruction-file pattern and before the
+    // generic dot-claude-slash rewrite below — otherwise the bare pattern
+    // consumes only the instruction-filename tail, leaving that prefix stale
+    // in place, and the generic rewrite then mutates the stale leftover too,
+    // producing a doubled trae-prefix segment ahead of the rules path instead
+    // of a single clean one. (Deliberately never spelling the instruction
+    // filename as one contiguous "CLAUDE" + dot + "md" token, and never
+    // spelling either malformed shape out as a literal contiguous string, in
+    // ANY comment in this function: this file ships verbatim into local
+    // `--trae` installs, where it is itself run through this same class of
+    // find/replace — a literal instruction-filename token sitting in a
+    // comment gets "fixed" right along with real code, and the emitted-content
+    // regression test added alongside this fix asserts neither malformed
+    // shape appears anywhere in the installed tree, comments included; this
+    // bit the fix itself twice during development.) All forms converge on the
+    // same concrete file (never a bare directory) so this stays in parity
+    // with the `trae.js` RUNTIME_CONTENT_DISPATCH entry.
+    converted = converted.replace(/`\.\/\.claude\/CLAUDE\.md`/g, '`.trae/rules/rules.md`');
+    converted = converted.replace(/\.\/\.claude\/CLAUDE\.md/g, '.trae/rules/rules.md');
+    converted = converted.replace(/`\.claude\/CLAUDE\.md`/g, '`.trae/rules/rules.md`');
+    converted = converted.replace(/\.claude\/CLAUDE\.md/g, '.trae/rules/rules.md');
+    // #2658 (found via the end-to-end install regression test, not the static
+    // trace above): `copyWithPathReplacement` runs a GENERIC dot-claude-slash
+    // -> runtime-config-dir rewrite on every .md file before calling this
+    // converter — for `~/.claude/`, `$HOME/.claude/`, AND `./.claude/` alike —
+    // substituting a runtime-appropriate `pathPrefix` this function is never
+    // given and cannot itself compute (it differs per install invocation: a
+    // relative `./.trae/` for a project-local install, an arbitrary absolute
+    // path for a local install rooted elsewhere, `~/.trae/` for a global one).
+    // So for source using any of those prefixed forms, the patterns above
+    // never fire here — this converter only ever sees the ALREADY-rewritten
+    // "<runtime-config-dir>/" + instruction-filename shape, with whatever
+    // prefix the install actually used. The generic pattern below preserves
+    // that prefix verbatim (via the capture group) and only fixes the
+    // filename suffix, rather than assuming a fixed `./.trae/` shape — a
+    // narrower fixed-prefix version of this pattern shipped first and still
+    // left the doubled-prefix defect live for the `$HOME/.claude/` and
+    // `~/.claude/` forms specifically (found the same way, one regression-test
+    // run later). Scoped to a `.trae/` tail so it cannot also swallow the
+    // unprefixed `./CLAUDE.md` form the very next pattern handles differently
+    // (discarding the prefix entirely, not preserving it). Must run before
+    // the bare pattern for the same consume-the-full-match-first reason.
+    converted = converted.replace(/`([^\s`]*\.trae\/)CLAUDE\.md`/g, '`$1rules/rules.md`');
+    converted = converted.replace(/([^\s`]*\.trae\/)CLAUDE\.md/g, '$1rules/rules.md');
+    converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.trae/rules/rules.md`');
+    converted = converted.replace(/\.\/CLAUDE\.md/g, '.trae/rules/rules.md');
+    converted = converted.replace(/`CLAUDE\.md`/g, '`.trae/rules/rules.md`');
+    converted = converted.replace(/\bCLAUDE\.md\b/g, '.trae/rules/rules.md');
     converted = converted.replace(/\.claude\/skills\//g, '.trae/skills/');
     converted = converted.replace(/\.\/\.claude\//g, './.trae/');
     converted = converted.replace(/\.claude\//g, '.trae/');
@@ -1126,7 +1244,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;
 }
 // DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
@@ -1180,7 +1299,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;
 }
 function convertClaudeCommandToCodebuddySkill(content, skillName) {
@@ -1260,7 +1380,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;
 }
 /**
@@ -1413,6 +1534,8 @@ 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_name\` — required by the collaboration schema; provide a descriptive name for each spawned task
+- \`fork_turns\` — optional parameter controlling turn-forking depth; coexists with \`fork_context\` (not a replacement)
 - \`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
@@ -1449,11 +1572,13 @@ Spawn restriction:
   defaulting to inline execution.
 
 Parallel fan-out:
-- Spawn multiple agents → collect agent IDs → \`wait(ids)\` for all to complete
+- Spawn multiple agents → collect agent IDs → \`collaboration.wait_agent(timeout_ms=...)\` for each to complete
+- Do NOT use \`functions.wait(cell_id=...)\` — that is an unrelated exec-cell tool, not the collaboration wait
 
 Result parsing:
 - Look for structured markers in agent output: \`CHECKPOINT\`, \`PLAN COMPLETE\`, \`SUMMARY\`, etc.
-- \`close_agent(id)\` after collecting results from each agent
+- \`close_agent(id)\` after collecting results — but only if \`close_agent\` is visible in the current
+  tool schema (check via \`tool_search\` first, same schema-detection gate as \`spawn_agent\` above)
 </codex_skill_adapter>`;
 }
 function convertClaudeCommandToCodexSkill(content, skillName) {
@@ -2038,8 +2163,9 @@ function convertClaudeAgentToQwenAgent(content) {
     let converted = content;
     if (_b['CLAUDE.md'])
         converted = converted.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
+    // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
     if (_b['Claude Code'])
-        converted = converted.replace(/\bClaude Code\b/g, _b['Claude Code']);
+        converted = applyClaudeCodeBrandSwap(converted, _b['Claude Code']);
     if (_b['.claude/'])
         converted = converted.replace(/\.claude\//g, _b['.claude/']);
     const { frontmatter, body } = extractFrontmatterAndBody(converted);
@@ -2342,7 +2468,8 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             const _b = _hostBehaviors(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, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
@@ -2366,7 +2493,8 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             const _b = _hostBehaviors(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, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
@@ -2633,10 +2761,15 @@ module.exports = {
     buildKimiAgentArtifacts,
     convertClaudeToCursorMarkdown,
     convertClaudeCommandToCursorSkill,
-    convertClaudeCommandToCursorCommand,
     convertClaudeToWindsurfMarkdown,
     convertClaudeCommandToWindsurfSkill,
     convertClaudeCommandToWindsurfWorkflow,
+    // #2931: single-sourced brand-swap helper (was duplicated verbatim in
+    // bin/install.js — the exact drift class this PR exists to reduce). Used
+    // internally by convertClaudeToWindsurfMarkdown/convertClaudeToAugmentMarkdown
+    // above and bound from here by the remaining bin/install.js converters
+    // (Cursor/Trae/CodeBuddy/Cline) that still brand-swap inline.
+    applyClaudeCodeBrandSwap,
     convertClaudeToAugmentMarkdown,
     convertClaudeCommandToAugmentSkill,
     convertClaudeToTraeMarkdown,

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -19,7 +19,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
-const { stageSkillsForProfile, stageAgentsForProfile, stageAgentsForRuntimeWithConverter, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
+const { stageSkillsForProfile, stageAgentsForRuntimeWithConverter, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const conversionExports = runtimeArtifactConversion;
@@ -117,7 +117,17 @@ function agentsKind(destSubpath, prefix, configDir) {
         kind: 'agents',
         destSubpath,
         prefix,
-        stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
+        // #2995: a `converter: null` agents entry (claude local, zcode) previously
+        // staged via stageAgentsForProfile — a RAW byte copy that never reads content
+        // into JS, so gsd:section markers shipped verbatim. Route through the
+        // composing stager with an identity converter instead: same output as the raw
+        // copy for an unmarked agent, markers stripped for a marked one. Routing both
+        // agent kinds through the stager collapses what were five independent agent
+        // read points down to three compose call sites: this stager, bin/install.js's
+        // inline agent loop, and installCodexConfig's per-agent .toml writer. The
+        // exhaustive per-runtime sweep in tests/agent-fragments-emission.install.test.cjs
+        // is what keeps a fourth from appearing uncomposed.
+        stage: (resolved) => stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, (content) => content),
     };
 }
 /**
@@ -185,7 +195,9 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
         prefix,
         stage: (resolved) => {
             const buildKimiAgentArtifacts = conversionExports['buildKimiAgentArtifacts'];
-            const stagedAgents = stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved);
+            // #2995: compose at staging (identity converter) so the readFileSync below
+            // sees marker-free content — same single composing stager as agentsKind.
+            const stagedAgents = stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, (content) => content);
             const subagents = [];
             if (node_fs_1.default.existsSync(stagedAgents)) {
                 for (const entry of node_fs_1.default.readdirSync(stagedAgents, { withFileTypes: true })) {