@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -21,21 +21,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_fs_1 = __importDefault(require("node:fs"));
+// #2874 (ADR-58 cleanup phase): route this module's content-rewrite-pass fs
+// calls through the installRuntimeArtifacts call tree's injectable seam —
+// see install-fs-adapter.cts's module doc. Resolves to real `node:fs` unless
+// the top-level installRuntimeArtifacts call injected a `deps.fs`. These
+// walkers operate on already-staged temp directories (never the real GSD
+// source tree or the real install destination directly), so routing them is
+// unconditionally safe.
+const installFsAdapter = require("./install-fs-adapter.cjs");
+const { installFs, mkInstallTempDir } = installFsAdapter;
 const commandRoster = require("./command-roster.cjs");
 const { readGsdCommandNames, transformContentToHyphen } = commandRoster;
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const { getDirName } = runtimeNamePolicy;
 const capabilityRegistry = require("./capability-registry.cjs");
+const hostIntegration = require("./host-integration.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const pattern_cjs_1 = require("./pattern.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// #2870: install-scope.cts is a leaf-tier sibling (imports only
+// runtime-homes.cjs + node builtins, never this module) — no cycle. See the
+// isGlobal sites below for why the boolean projection is centralized here too.
+const install_scope_cjs_1 = require("./install-scope.cjs");
+// #2875 Part 2: install-effort-resolver.cjs is a leaf-tier sibling (#2071) —
+// used by applyAgentFrontmatterExtensions below to read the SAME merged
+// effort config the install-time Claude .md injection has always read,
+// without this module reaching upward into bin/install.js (ADR-1508).
+const installEffortResolver = require("./install-effort-resolver.cjs");
+const { readGsdEffectiveEffortConfig, resolveInstallTimeEffort, _getGsdEffortCatalog } = installEffortResolver;
 // #1383: resolve GSD's version WITHOUT a top-level
 // `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
@@ -267,11 +292,8 @@ function buildKiloAgentPermissionBlock(claudeTools) {
     }
     return lines;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 function replaceRelativePathReference(content, fromPath, toPath) {
-    const escapedPath = escapeRegExp(fromPath);
+    const escapedPath = (0, pattern_cjs_1.escapeRegex)(fromPath);
     return content.replace(new RegExp(`(^|[^A-Za-z0-9_./-])${escapedPath}`, 'g'), (_, prefix) => `${prefix}${toPath}`);
 }
 /**
@@ -364,9 +386,6 @@ function skillFrontmatterName(skillDirName) {
     // Return the hyphen form as-is (gsd-<cmd>) — canonical since #2808.
     return skillDirName;
 }
-function normalizeClaudeSkillEffort(effort) {
-    return effort === 'xhigh' ? 'max' : effort;
-}
 /**
  * Qwen Code skills accept an optional numeric `priority` frontmatter field.
  * Per the Qwen skills spec (qwen-code/docs/users/features/skills.md, verified
@@ -421,10 +440,13 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
     const description = extractFrontmatterField(frontmatter, 'description') || '';
     const argumentHint = extractFrontmatterField(frontmatter, 'argument-hint');
     const agent = extractFrontmatterField(frontmatter, 'agent');
-    // #769: preserve context: and effort: from source command files so they
-    // are emitted into the installed SKILL.md frontmatter unchanged.
+    // #769: preserve context: from source command files so it is emitted into
+    // the installed SKILL.md frontmatter unchanged. (#3151: effort: is no longer
+    // emitted into skill frontmatter — a static effort value changes
+    // output_config.effort on invocation and invalidates the caller's prompt
+    // cache at both scope boundaries; the reporter's owned measurement confirms
+    // the mechanism. The separate agent-effort surface is tracked by #3160.)
     const context = extractFrontmatterField(frontmatter, 'context');
-    const effort = extractFrontmatterField(frontmatter, 'effort');
     // Preserve allowed-tools as YAML multiline list (Claude native format)
     const toolsMatch = frontmatter.match(/^allowed-tools:\s*\n((?:\s+-\s+.+\n?)*)/m);
     let toolsBlock = '';
@@ -464,19 +486,100 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
         fm += `argument-hint: ${yamlQuote(argumentHint)}\n`;
     if (agent)
         fm += `agent: ${agent}\n`;
-    // #769: emit context: and effort: when present so the runtime can honour
-    // them natively (context: fork = isolated subagent window; effort: =
-    // token-budget tier). Fields are Claude-specific; unknown frontmatter
-    // fields are silently ignored by other runtimes (backward-compatible).
+    // #769: emit context: when present so the runtime can honour it natively
+    // (context: fork = isolated subagent window). Claude-specific; unknown
+    // frontmatter fields are silently ignored by other runtimes (backward-compatible).
+    // (#3151: effort: is intentionally NOT emitted into skill frontmatter — a
+    // static effort value changes output_config.effort on invocation and
+    // invalidates the caller's prompt cache at both scope boundaries.)
     if (context)
         fm += `context: ${context}\n`;
-    if (effort)
-        fm += `effort: ${normalizeClaudeSkillEffort(effort)}\n`;
     if (toolsBlock)
         fm += toolsBlock;
     fm += '---';
     return `${fm}\n${normalizedBody}`;
 }
+// #2873 (4b) — spec-root reachability. Matches ONLY a line that is a real
+// `@~/.claude/gsd-core/workflows/<stem>.md` include: line-start `@`, exact
+// spec-root shape, nothing else on the line. This is deliberately narrower
+// than "any line mentioning gsd-core/workflows" so prose mentions and
+// `references/`/`templates/`/`@.planning/...` includes are never touched
+// (rows 24/25). CRLF-safe: an optional trailing `\r` is captured and
+// preserved rather than dropped.
+const WORKFLOW_SPEC_ROOT_INCLUDE_RE = /^@~\/\.claude\/gsd-core\/workflows\/([A-Za-z0-9._-]+)\.md[ \t]*(\r?)$/gm;
+/**
+ * Rewrite a static global-scope Claude skill `@`-include of the command's own
+ * workflow spec into an imperative two-step resolution the agent performs at
+ * runtime: prefer the project-local spec (cwd-relative), fall back to the
+ * global spec, and treat "neither exists" as a visible failure rather than a
+ * silent no-spec proceed.
+ *
+ * WHY this can't stay a static `@`-include (even a relative one): Claude Code
+ * documents relative `@`-paths as resolving against the file *containing* the
+ * import, which for a global skill is `~/.claude/skills/gsd-<stem>/` — not
+ * the project's working directory. `@./.claude/...` would therefore always
+ * resolve inside the skill's own install directory, never the project, so
+ * there is no static include syntax that can express "prefer local, fall
+ * back to global". This function exists precisely so that resolution can be
+ * performed by the agent, not the host's pre-expansion.
+ *
+ * Scope-free by design: this function does not know or care whether it is
+ * being applied to a global or local artifact, or which runtime — that
+ * judgment belongs to the caller (`skillsKind` in
+ * `runtime-artifact-layout.cts`, the one site that knows install scope).
+ * Applying it to a body with no workflow include is a no-op (row 26); a body
+ * with two independent workflow includes has each rewritten independently
+ * (row 27); an include inside a fenced code block or wrapped in inline
+ * backticks is left untouched (the backtick case is already excluded by the
+ * line-start anchor, since a backtick-wrapped line does not begin with `@`).
+ * Idempotent: the replacement text never begins with `@` and never matches
+ * `WORKFLOW_SPEC_ROOT_INCLUDE_RE`, so re-applying this function to its own
+ * output is a no-op.
+ *
+ * Fence detection reuses `scanFencedBlocks` (markdown-sectionizer.cts) — the
+ * same CommonMark-correct state machine `stripFencedCode`/`extractFencedBlock`
+ * are built on — instead of a hand-rolled "any delimiter line toggles
+ * open/closed" tracker. A naive toggle is wrong under CommonMark: a fence
+ * opened with ``` is NOT closed by a ~~~ line (closer must share the
+ * opener's delimiter character and have run length >= the opener's), so a
+ * mismatched delimiter is fence CONTENT, not a boundary. #2873 review.
+ */
+function resolveSpecRootReference(body) {
+    if (typeof body !== 'string' || body.length === 0)
+        return body;
+    if (!body.includes('@~/.claude/gsd-core/workflows/'))
+        return body;
+    // Collect [start, end) character-offset ranges covered by fenced code
+    // blocks so matches inside them are skipped. An unterminated trailing
+    // fence covers to the end of the string (still "inside a fence").
+    const lines = body.split('\n');
+    const lineStartOffsets = [];
+    {
+        let offset = 0;
+        for (const line of lines) {
+            lineStartOffsets.push(offset);
+            offset += line.length + 1; // +1 for the '\n' separator
+        }
+    }
+    const fenceRanges = (0, markdown_sectionizer_cjs_1.scanFencedBlocks)(lines).map(({ openLineIdx, closeLineIdx }) => {
+        const start = lineStartOffsets[openLineIdx];
+        const end = closeLineIdx === -1
+            ? body.length
+            : lineStartOffsets[closeLineIdx] + lines[closeLineIdx].length;
+        return [start, end];
+    });
+    const isInsideFence = (offset) => fenceRanges.some(([start, end]) => offset >= start && offset < end);
+    return body.replace(WORKFLOW_SPEC_ROOT_INCLUDE_RE, (match, stem, cr, offset) => {
+        if (isInsideFence(offset))
+            return match;
+        return (`To load this command's workflow spec: check for ` +
+            `\`.claude/gsd-core/workflows/${stem}.md\` relative to the current working ` +
+            `directory first (project-local); if it is not there, fall back to ` +
+            `\`~/.claude/gsd-core/workflows/${stem}.md\` (the global install). If ` +
+            `neither file exists, stop — a workflow spec is required and none was found.` +
+            cr);
+    });
+}
 function normalizeKimiSkillName(skillName) {
     let text = String(skillName || '').trim().toLowerCase();
     if (text.startsWith('/'))
@@ -492,7 +595,7 @@ function normalizeKimiSkillName(skillName) {
 function convertGsdCommandReferencesToKimiSkillInvocations(content, cmdNames) {
     if (!Array.isArray(cmdNames) || cmdNames.length === 0)
         return content;
-    const commands = [...cmdNames].sort((a, b) => b.length - a.length).map(escapeRegExp);
+    const commands = [...cmdNames].sort((a, b) => b.length - a.length).map(pattern_cjs_1.escapeRegex);
     const commandGroup = commands.join('|');
     const colonPattern = new RegExp(`(?<![A-Za-z0-9_/:.-])/?gsd:(${commandGroup})(?=[^A-Za-z0-9_-]|$)`, 'g');
     const hyphenPattern = new RegExp(`(?:/|\\$)gsd-(${commandGroup})(?=[^A-Za-z0-9_-]|$)`, 'g');
@@ -848,8 +951,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 +994,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 +1059,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 +1100,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 +1148,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 +1212,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 +1277,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 +1337,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 +1392,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 +1473,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;
 }
 /**
@@ -1412,7 +1626,9 @@ Typed mapping (agent_type-capable schema only):
   to \`spawn_agent\` when the runtime/tool supports it. Omit missing, empty,
   inherited, or unsupported values; do not invent one-off effort literals in
   workflow prose.
-- \`fork_context: false\` by default — GSD agents load their own context via \`<files_to_read>\` blocks
+- \`fork_context: false\` by default — GSD agents load their own context via \`<required_reading>\` 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 +1665,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 +2256,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);
@@ -2062,6 +2281,106 @@ function convertClaudeAgentToQwenAgent(content) {
     fm += '---';
     return `${fm}\n${body}`;
 }
+/**
+ * Convert a Claude Code agent .md for ZCode (#3384).
+ *
+ * ZCode is Claude-shaped (same frontmatter, same named-dispatch subagents), so
+ * the file is preserved verbatim EXCEPT the `tools:` grant list: ZCode's
+ * dispatcher treats every `mcp__<server>__*` entry as a REQUIRED MCP server and
+ * hard-fails the subagent spawn (CONFIGURATION_ERROR: "Required MCP server is
+ * not connected") whenever it is not connected, whereas Claude Code treats the
+ * same entries as an optional allowlist. The `mcp__*` entries are stripped at
+ * install time — the same exclusion Kimi's converter applies via
+ * convertKimiToolName — so subagent spawns succeed with zero MCP servers
+ * configured; connected servers' tools remain reachable (auto-discovered by the
+ * host, not granted by frontmatter).
+ *
+ * Line-surgical by design: ONLY `tools:` lines inside the frontmatter are
+ * touched, so every other byte (description, color, commented-out blocks, the
+ * body) survives identically. Handles both shapes GSD emits — the inline comma
+ * list (`tools: A, B, C`) and the YAML block list (`tools:` + `- A` items).
+ * An agent whose filtered grant list becomes empty (every grant was `mcp__*`)
+ * drops the `tools:` key entirely: an absent key inherits the full toolkit,
+ * which is the degrade-gracefully outcome, never a toolless subagent.
+ *
+ * Byte-identical for an agent with no `mcp__*` grants (the common case) and
+ * for an agent with no frontmatter at all.
+ */
+function convertClaudeAgentToZcodeAgent(content) {
+    // Fast path: no MCP grant token anywhere means nothing to strip. (A body
+    // mention alone is not a grant — the line scan below finds no tools-line
+    // change and returns `content` unchanged anyway; this just skips the scan.)
+    if (!content.includes('mcp__'))
+        return content;
+    const lines = content.split('\n');
+    if (lines[0] !== '---')
+        return content;
+    let fmEnd = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === '---') {
+            fmEnd = i;
+            break;
+        }
+    }
+    if (fmEnd === -1)
+        return content; // unterminated frontmatter — leave verbatim
+    const out = [];
+    let changed = false;
+    let i = 1;
+    while (i < fmEnd) {
+        const line = lines[i];
+        const inlineTools = /^tools:[ \t]*(.+)$/.exec(line);
+        if (inlineTools) {
+            const grants = inlineTools[1].split(',').map((tool) => tool.trim()).filter((tool) => tool !== '');
+            const kept = grants.filter((tool) => !tool.startsWith('mcp__'));
+            if (kept.length === grants.length) {
+                out.push(line); // no mcp__* grants — keep the line byte-identical
+            }
+            else if (kept.length > 0) {
+                out.push(`tools: ${kept.join(', ')}`);
+                changed = true;
+            }
+            else {
+                changed = true; // every grant was mcp__*: drop the tools key entirely
+            }
+            i++;
+            continue;
+        }
+        if (/^tools:[ \t]*$/.test(line)) {
+            // Block-list form: collect the following `- item` lines.
+            const items = [];
+            let j = i + 1;
+            while (j < fmEnd && /^([ \t]*)-[ \t]*(\S.*)$/.test(lines[j])) {
+                items.push(lines[j]);
+                j++;
+            }
+            const kept = items.filter((item) => {
+                const name = /^([ \t]*)-[ \t]*(\S.*)$/.exec(item)[2].trim();
+                return !name.startsWith('mcp__');
+            });
+            if (kept.length !== items.length) {
+                changed = true;
+                if (kept.length > 0) {
+                    out.push(line);
+                    out.push(...kept);
+                } // else: drop the tools key and all its items
+            }
+            else {
+                out.push(line, ...items);
+            }
+            i = j;
+            continue;
+        }
+        out.push(line);
+        i++;
+    }
+    if (!changed)
+        return content;
+    // Opening delimiter + transformed frontmatter + closing delimiter + body.
+    out.unshift(lines[0]);
+    out.push(...lines.slice(fmEnd));
+    return out.join('\n');
+}
 function convertClaudeAgentToCodebuddyAgent(content) {
     const converted = convertClaudeToCodebuddyMarkdown(content);
     const { frontmatter, body } = extractFrontmatterAndBody(converted);
@@ -2082,6 +2401,48 @@ function convertClaudeAgentToClineAgent(content) {
     const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
     return `${cleanFrontmatter}\n${body}`;
 }
+/**
+ * Apply a runtime's descriptor-declared `hostBehaviors.brandingRewrites` to an
+ * agent body — the three literal-substring replaces the inline agent loop
+ * (bin/install.js) previously hardcoded per-branding-runtime (qwen/hermes):
+ *   CLAUDE.md    -> brandingRewrites['CLAUDE.md']
+ *   Claude Code  -> brandingRewrites['Claude Code']  (word-boundary, \bClaude Code\b)
+ *   .claude/     -> brandingRewrites['.claude/']
+ *
+ * Data-driven (#2875 Part 2 / J10): reads the rewrite table from the
+ * runtime's OWN descriptor rather than hardcoding any runtime's strings, so a
+ * runtime declaring a different `brandingRewrites` table gets its own
+ * rewrites applied automatically. A runtime with no `brandingRewrites`
+ * declared returns `content` unchanged (no rewrite table to apply).
+ *
+ * Byte-identical to the inline loop's `else if (_hostBehaviors(runtime).brandingRewrites)`
+ * branch, including plain (non-word-boundary) `.replace(/\bClaude Code\b/g, ...)`
+ * semantics — J9.
+ */
+function applyAgentBrandingRewrites(content, runtime) {
+    const _b = _hostBehaviors(runtime).brandingRewrites;
+    if (!_b)
+        return content;
+    let converted = content;
+    if (_b['CLAUDE.md'])
+        converted = converted.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
+    if (_b['Claude Code'])
+        converted = converted.replace(/\bClaude Code\b/g, _b['Claude Code']);
+    if (_b['.claude/'])
+        converted = converted.replace(/\.claude\//g, _b['.claude/']);
+    return converted;
+}
+/**
+ * Named branding converter for Hermes agents (#2875 Part 2 / J9-J10).
+ * `convertedAgentsKind` dispatches converters by exported name, so a named
+ * export is required even though the transform itself is fully generic
+ * (`applyAgentBrandingRewrites`) — resolved from
+ * `capabilities/hermes/capability.json`'s `hostBehaviors.brandingRewrites`,
+ * never hardcoded here.
+ */
+function convertClaudeAgentToHermesAgent(content) {
+    return applyAgentBrandingRewrites(content, 'hermes');
+}
 /**
  * Convert Claude Code agent markdown to Codex agent format.
  * Applies base markdown conversions, then adds a <codex_agent_role> header
@@ -2194,20 +2555,145 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
 const NON_CLAUDE_RUNTIMES = Object.keys(capabilityRegistry.runtimes)
     .filter((id) => id !== 'claude')
     .sort();
+/**
+ * #2652: The isolation a runtime can actually negotiate at dispatch time,
+ * resolved from the registry exactly as `gsd_run query dispatch-isolation`
+ * resolves it at runtime (`routeDispatchIsolation`, gsd-core/bin/gsd-tools.cjs):
+ * the declared value must be in the closed vocabulary, a `harness-worktree`
+ * host must also declare the flag the scheduler passes, and an
+ * `orchestrator-worktree` host must carry a descriptor that resolves. Anything
+ * else — unknown runtime, `undocumented`, out-of-vocabulary, a throw — is
+ * `none` (ADR-1239, "Fail-closed").
+ *
+ * Install time cannot know the worktree path a future dispatch will target, so
+ * the descriptor is probed with a placeholder; `resolveOrchestratorExec` fails
+ * only on descriptor shape, never on a well-formed target's value.
+ *
+ * @private — exported as `_negotiatedDispatchIsolation` for tests.
+ */
+function _negotiatedDispatchIsolation(runtime) {
+    try {
+        const runtimeEntry = capabilityRegistry?.runtimes?.[runtime] ?? null;
+        const declared = runtimeEntry?.runtime?.hostIntegration?.dispatch?.isolation ?? null;
+        if (declared === 'harness-worktree') {
+            const declaredFlag = runtimeEntry?.runtime?.harnessIsolationFlag ?? null;
+            return typeof declaredFlag === 'string' && declaredFlag.length > 0
+                ? 'harness-worktree'
+                : 'none';
+        }
+        if (declared === 'orchestrator-worktree') {
+            return hostIntegration.resolveOrchestratorExec(runtimeEntry?.runtime?.orchestratorExec, '/gsd-orchestrator-worktree-probe').ok
+                ? 'orchestrator-worktree'
+                : 'none';
+        }
+        return 'none';
+    }
+    catch {
+        return 'none';
+    }
+}
 /**
  * #1521: Every non-Claude runtime resolves its own runtime identity from a
- * runtime-neutral config, and defaults workflow.use_worktrees to false —
- * GSD's worktree isolation uses Claude Code's isolation="worktree" spawn
- * parameter, which no other runtime honors. Stamped into the emitted
- * workflow runtime-resolution blocks. (Generalizes the Codex-only #1515 fix.)
+ * runtime-neutral config. Stamped into the emitted workflow runtime-resolution
+ * blocks. (Generalizes the Codex-only #1515 fix.)
+ *
+ * #1521 also stamped `workflow.use_worktrees` to default false for every
+ * non-Claude runtime, because GSD's worktree isolation was Claude Code's
+ * `isolation="worktree"` spawn parameter and no other runtime honored it.
+ * #2584 removed that premise: isolation is now a negotiated capability
+ * (`dispatch.isolation`), and Cursor declares `harness-worktree` while Codex,
+ * OpenCode, Kimi and Kimi Code declare `orchestrator-worktree`. Stamping the
+ * false default for those hosts resolved `USE_WORKTREES=false` before
+ * `dispatch.isolation` was ever consulted, so a runtime that declares worktree
+ * support still got `ISOLATION=none` — judged by its name after all, which is
+ * the defect #2652 exists to remove. The stamp is therefore scoped to the
+ * runtimes whose negotiated isolation really is `none`, where the default it
+ * writes is the outcome the resolver would reach anyway.
  *
  * @private — exported as `_stampNonClaudeRuntimeDefaults` for tests.
  */
 function _stampNonClaudeRuntimeDefaults(content, runtime) {
-    content = content.replace(/config-get workflow\.use_worktrees --raw 2>\/dev\/null \|\| echo "true"/g, 'config-get workflow.use_worktrees --default false --raw 2>/dev/null || echo "false"');
+    if (_negotiatedDispatchIsolation(runtime) === 'none') {
+        content = content.replace(/config-get workflow\.use_worktrees --raw 2>\/dev\/null \|\| echo "true"/g, 'config-get workflow.use_worktrees --default false --raw 2>/dev/null || echo "false"');
+    }
     content = content.replace(/config-get runtime --default claude --raw 2>\/dev\/null \|\| echo "claude"/g, `config-get runtime --default ${runtime} --raw 2>/dev/null || echo "${runtime}"`);
     return content;
 }
+/**
+ * #3544 (extending #3133's fix): restore `@$HOME<suffix>` `@`-file-reference
+ * lines back to their tilde equivalent (`@~<suffix>`) in Claude-emitted
+ * content whose pathPrefix is the `$HOME` form. This is a NARROW,
+ * context-sensitive correction layered on top of the blanket `~/.claude/` /
+ * `$HOME/.claude/` -> pathPrefix substitution every Claude emit path
+ * applies: that blanket substitution MUST keep emitting `$HOME` for global
+ * installs — shell commands embedded in workflow/command bodies (e.g.
+ * `node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs"`) need it, since `~` does
+ * not expand inside double-quoted shell strings (#1284). But Claude Code's
+ * own `@`-import resolver does the opposite: it documents `~` expansion and
+ * does NOT expand `$HOME`. That is not merely undocumented — a controlled
+ * `/context` measurement showed an `@$HOME/…` import loading nothing (see
+ * .gsd/bug/fix-3544-home-expansion-spec-tree/10-diagnosis.md's ADDENDUM). No
+ * automated test can verify *resolution* inside a live Claude Code session
+ * (nothing in CI can spawn one and read `/context`); every test here — unit
+ * and spawned-installer alike — verifies only the emitted STRING takes the
+ * `~` form Claude Code documents as expanding. A single pathPrefix string
+ * cannot satisfy both the shell and the `@`-import consumer, so this runs as
+ * a second, `@`-anchored pass AFTER the blanket substitution.
+ *
+ * #3133 first applied this restore inline in `_applyRuntimeRewrites`'s
+ * `case 'claude'` below (the skill/command staging pipeline). #3544 found
+ * the identical defect in bin/install.js's `copyWithPathReplacement` — the
+ * `gsd-core/` spec-tree emit path, which never had the restore step, so
+ * every `@~/.claude/gsd-core/…` include in a global install's workflows/
+ * references tree silently resolved to nothing (54 includes across 22 files
+ * on a live install, per the diagnosis). Both call sites now share this one
+ * implementation instead of drifting independently (DEFECT.GENERATIVE-FIX).
+ *
+ * No-op unless `pathPrefix` is the `$HOME` form — local installs already
+ * bake an absolute, `@`-resolvable pathPrefix and are unaffected, as are
+ * every non-Claude runtime (never called for them).
+ *
+ * #3544 review (2nd pass): the first cut of this function hardcoded the
+ * literal `.claude/` segment, so it silently no-opped for any global install
+ * under a non-default `--config-dir` (e.g. `~/.claude-work`) — reproducing
+ * the exact defect #3544 fixes, just one directory name later. This ALSO
+ * corrects the same latent gap in #3133's original path, since both call
+ * sites share this one implementation. Fixed by deriving the rewrite from
+ * `pathPrefix` itself rather than a hardcoded directory name: the tilde
+ * equivalent of any `$HOME`-form prefix is `'~' + pathPrefix.slice(5)`
+ * (`'$HOME'.length === 5`), so the transform generalizes to any config-dir
+ * name with no runtime-specific literal.
+ *
+ * #3544 review (2nd pass), quote-awareness: the anchor is a negative
+ * lookbehind for a preceding quote character, NOT a line-start anchor —
+ * Claude Code documents `@`-references as valid "anywhere in your
+ * CLAUDE.md" (e.g. `See @README for project overview`), so anchoring to
+ * line-start would miss a legitimate mid-line reference. The lookbehind
+ * instead guards the one demonstrated false-positive: a quoted shell string
+ * like `echo "@$HOME/.claude/x"`, where rewriting `$HOME` to `~` inside
+ * double quotes reintroduces the #1284 failure mode (`~` does not expand in
+ * double-quoted shell). Deliberately NOT fenced-code-block aware (unlike
+ * `resolveSpecRootReference`'s `scanFencedBlocks` use above): this pass
+ * targets genuine `@`-import lines and inline shell references across the
+ * whole emitted corpus, and today there are zero occurrences anywhere in the
+ * tree of an `@$HOME<suffix>` sequence inside a fenced code block (the
+ * quote-guard already closes the one reachable false-positive class).
+ * Layering `scanFencedBlocks` on top would roughly double this function's
+ * size to guard an undemonstrated case — the opposite of the brief's
+ * "simpler, not more complex" direction. If a fenced example ever needs this
+ * literal sequence, add fence-awareness then, with a regression test proving
+ * the fence is real.
+ *
+ * @private — exported as `_restoreClaudeGlobalAtRefTilde` for tests and for
+ * bin/install.js's `copyWithPathReplacement`.
+ */
+function restoreClaudeGlobalAtRefTilde(content, pathPrefix) {
+    if (typeof pathPrefix !== 'string' || !pathPrefix.startsWith('$HOME'))
+        return content;
+    const tildeEquivalent = '~' + pathPrefix.slice('$HOME'.length);
+    const atRefRe = new RegExp(`(?<!["'])@${(0, pattern_cjs_1.escapeRegex)(pathPrefix)}`, 'g');
+    return content.replace(atRefRe, `@${tildeEquivalent}`);
+}
 /**
  * Apply the per-runtime rewrite table to a single content string.
  * Relocated from bin/install.js `_applyRuntimeRewrites`.
@@ -2284,7 +2770,7 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             // #2097: dot-dir self-references (~/.augment/…) → resolved prefix,
             // dirName-derived (no runtime literal). getDirName('augment') resolves
             // to '.augment', so this is byte-identical to the prior hardcoded regexes.
-            const _dd = escapeRegExp(dirName);
+            const _dd = (0, pattern_cjs_1.escapeRegex)(dirName);
             content = content.replace(new RegExp('~/' + _dd + '/', 'g'), pathPrefix);
             content = content.replace(new RegExp('\\$HOME/' + _dd + '/', 'g'), pathPrefix);
             content = content.replace(new RegExp('~/' + _dd + '(?![\\w-])', 'g'), normalizedPathPrefix);
@@ -2302,7 +2788,7 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             // #2094: descriptor-driven — dirName resolves to '.trae' via
             // getDirName()/localConfigDir, so this regex is built rather than
             // hardcoded as `/~\/\.trae\//g` (byte-identical output for trae).
-            content = content.replace(new RegExp('~/' + escapeRegExp(dirName) + '/', 'g'), pathPrefix);
+            content = content.replace(new RegExp('~/' + (0, pattern_cjs_1.escapeRegex)(dirName) + '/', 'g'), pathPrefix);
             content = processAttribution(content, attribution);
             break;
         case 'codebuddy':
@@ -2328,6 +2814,10 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+            // #3133 / #3544: restore @-file-reference lines to the tilde form
+            // Claude actually expands — see restoreClaudeGlobalAtRefTilde's doc
+            // comment above for why this must be a separate, @-anchored pass.
+            content = restoreClaudeGlobalAtRefTilde(content, pathPrefix);
             content = processAttribution(content, attribution);
             break;
         // Descriptor-driven brand literals (ADR-1239 / #2092): the qwen/hermes
@@ -2342,7 +2832,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 +2857,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);
@@ -2413,18 +2905,18 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
  * @param attribution  Co-Authored-By value (string | null | undefined)
  */
 function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGlobal = false, attribution = undefined) {
-    if (!node_fs_1.default.existsSync(stagedDir))
+    if (!installFs().existsSync(stagedDir))
         return;
     const walkAndRewrite = (dir) => {
-        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        for (const entry of installFs().readdirSync(dir, { withFileTypes: true })) {
             const fullPath = node_path_1.default.join(dir, entry.name);
             if (entry.isDirectory()) {
                 walkAndRewrite(fullPath);
             }
             else if (entry.name.endsWith('.md')) {
-                let content = node_fs_1.default.readFileSync(fullPath, 'utf8');
+                let content = installFs().readFileSync(fullPath, 'utf8');
                 content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal, attribution);
-                node_fs_1.default.writeFileSync(fullPath, content);
+                installFs().writeFileSync(fullPath, content);
             }
         }
     };
@@ -2449,14 +2941,14 @@ function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGl
  * @returns {string} path to the temp dir (caller is responsible for cleanup)
  */
 function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix, isGlobal = false, attribution = undefined) {
-    if (!node_fs_1.default.existsSync(stagedDir))
+    if (!installFs().existsSync(stagedDir))
         return stagedDir;
-    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-cmd-rewrites-'));
+    const tempDir = mkInstallTempDir('gsd-cmd-rewrites-');
     try {
-        for (const entry of node_fs_1.default.readdirSync(stagedDir, { withFileTypes: true })) {
+        for (const entry of installFs().readdirSync(stagedDir, { withFileTypes: true })) {
             if (!entry.isFile() || !entry.name.endsWith('.md'))
                 continue;
-            let content = node_fs_1.default.readFileSync(node_path_1.default.join(stagedDir, entry.name), 'utf8');
+            let content = installFs().readFileSync(node_path_1.default.join(stagedDir, entry.name), 'utf8');
             content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal, attribution);
             // #2097 (ADR-1239): descriptor-driven — commandBodyConverter name comes
             // from runtime.hostBehaviors instead of a hardcoded runtime-name branch.
@@ -2464,18 +2956,52 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
             if (_cmdConv && COMMAND_BODY_CONVERTERS[_cmdConv]) {
                 content = COMMAND_BODY_CONVERTERS[_cmdConv](content);
             }
-            node_fs_1.default.writeFileSync(node_path_1.default.join(tempDir, entry.name), content);
+            installFs().writeFileSync(node_path_1.default.join(tempDir, entry.name), content);
         }
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+            installFs().rmSync(tempDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
     return tempDir;
 }
+/**
+ * #2873 (4b) — second pass over a staged skills directory, run strictly AFTER
+ * `applyRuntimeContentRewritesInPlace`. That pass's `case 'claude':` branch
+ * unconditionally rewrites any bare (non-`@`-prefixed) `~/.claude/` substring
+ * in the body to the computed pathPrefix (`$HOME/.claude/` for a global
+ * install) and restores ONLY the `@`-prefixed form back to `~`
+ * (`@$HOME/.claude/` → `@~/.claude/`). `resolveSpecRootReference`'s
+ * replacement text is deliberately imperative prose containing a literal,
+ * non-`@`-prefixed `~/.claude/gsd-core/workflows/<stem>.md` — running it
+ * BEFORE the pass above would let that literal tilde text get silently
+ * mangled into the undocumented `$HOME/` form the design explicitly rejects.
+ * Running it here, after, means it only ever sees the FINAL
+ * `@~/.claude/gsd-core/workflows/<stem>.md` include line (which survives the
+ * pass above intact via its own `@`-guarded restore).
+ */
+function applySpecRootReferenceToStagedSkills(stagedDir) {
+    if (!installFs().existsSync(stagedDir))
+        return;
+    const walk = (dir) => {
+        for (const entry of installFs().readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (entry.name === 'SKILL.md') {
+                const content = installFs().readFileSync(fullPath, 'utf8');
+                const rewritten = resolveSpecRootReference(content);
+                if (rewritten !== content)
+                    installFs().writeFileSync(fullPath, rewritten);
+            }
+        }
+    };
+    walk(stagedDir);
+}
 /**
  * HIGH-LEVEL: In-place fs walk: rewrite all .md files under stagedDir for the given runtime.
  *
@@ -2492,16 +3018,30 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
  */
 function rewriteStagedSkillBodies(stagedDir, opts) {
     const { runtime, configDir, scope = 'global', homedir = () => node_os_1.default.homedir(), platform = process.platform, resolveAttribution, } = opts;
-    if (!node_fs_1.default.existsSync(stagedDir))
+    if (!installFs().existsSync(stagedDir))
         return;
     const resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir));
     const homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(homedir());
-    const isGlobal = scope === 'global';
+    // #2870: `scope` is defaulted to 'global' above, so it is never undefined
+    // here, and every reachable caller passes 'global' | 'local' | undefined —
+    // isGlobalScope's throw-on-out-of-union case is unreachable at this site.
+    const isGlobal = (0, install_scope_cjs_1.isGlobalScope)(scope);
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
     const pathPrefix = computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
     applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGlobal, attribution);
+    // #2873 (4b): claude, global scope only — see
+    // applySpecRootReferenceToStagedSkills's doc comment for why this MUST run
+    // after the rewrite pass above, not before. `rewriteStagedSkillBodies` is
+    // the skills-kind seam (`kind.kind === 'skills'`), so this never touches a
+    // 'commands' or 'agents' kind body (rows 24/25 unaffected), and claude has
+    // no skills-kind entry at local scope, so this is already structurally
+    // scoped to global (row 23) — the explicit isGlobal check is defense-in-depth
+    // against that descriptor wiring ever changing.
+    if (runtime === 'claude' && isGlobal) {
+        applySpecRootReferenceToStagedSkills(stagedDir);
+    }
 }
 /**
  * HIGH-LEVEL: Copy-to-temp then rewrite all .md files for the given runtime.
@@ -2521,11 +3061,14 @@ function rewriteStagedSkillBodies(stagedDir, opts) {
  */
 function rewriteStagedCommandBodies(stagedDir, opts) {
     const { runtime, configDir, scope = 'global', homedir = () => node_os_1.default.homedir(), platform = process.platform, resolveAttribution, } = opts;
-    if (!node_fs_1.default.existsSync(stagedDir))
+    if (!installFs().existsSync(stagedDir))
         return stagedDir;
     const resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir));
     const homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(homedir());
-    const isGlobal = scope === 'global';
+    // #2870: `scope` is defaulted to 'global' above, so it is never undefined
+    // here, and every reachable caller passes 'global' | 'local' | undefined —
+    // isGlobalScope's throw-on-out-of-union case is unreachable at this site.
+    const isGlobal = (0, install_scope_cjs_1.isGlobalScope)(scope);
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
     const pathPrefix = computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
@@ -2586,6 +3129,127 @@ function applyAgentPathRewrites(content, runtime, pathPrefix) {
     return content;
 }
 // ── End rewrite engine ────────────────────────────────────────────────────────
+/**
+ * Derive an agent's stem name from its source `.md` filename. Byte-identical
+ * to the inline agent loop's `entry.name.replace(/\.md$/, '')` (bin/install.js)
+ * — single-sourced here so the descriptor pipeline's per-agent resolution
+ * context (`agentCtx.agentName`, ADR-1235 §1 / #2875 Part 2 row I3) can never
+ * diverge from it. A filename with no trailing `.md` is returned unchanged
+ * (the regex has nothing to match) — I3's boundary row.
+ */
+function deriveAgentName(fileName) {
+    return fileName.replace(/\.md$/, '');
+}
+/**
+ * #443 — Inject `effort: <value>` into YAML frontmatter of a Claude .md agent
+ * file in a newline-agnostic way (LF and CRLF source files are both handled).
+ * Relocated verbatim from bin/install.js (#2875 Part 2) — see
+ * `applyAgentFrontmatterExtensions` below for the orchestration that calls it.
+ *
+ * The function:
+ *   - Detects the file's EOL (CRLF if the first `---` line ends with \r\n,
+ *     otherwise LF).
+ *   - Skips injection if an `effort:` key already exists in the frontmatter
+ *     (idempotent).
+ *   - Inserts `effort: <value>` immediately before the closing `---` delimiter,
+ *     using the same EOL as the surrounding frontmatter so the output file
+ *     stays EOL-consistent.
+ *   - Returns the original content unchanged when no YAML frontmatter is found.
+ */
+function injectEffortFrontmatter(content, effortValue) {
+    const eol = /^---\r\n/.test(content) ? '\r\n' : '\n';
+    const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
+    const match = fmRe.exec(content);
+    if (!match)
+        return content; // no YAML frontmatter — leave unchanged
+    const fmBody = match[1]; // content between the two `---` lines
+    if (/^effort:/m.test(fmBody))
+        return content;
+    const openLen = 3 + eol.length; // "---" + eol
+    const closingStart = match.index + openLen + fmBody.length;
+    const before = content.slice(0, closingStart);
+    const after = content.slice(closingStart);
+    return `${before}effort: ${effortValue}${eol}${after}`;
+}
+/**
+ * #767 — Inject `disallowedTools: <value>` into the YAML frontmatter of a
+ * Claude .md agent. Mirrors injectEffortFrontmatter: idempotent (skips if
+ * disallowedTools: already present), inserts immediately before the closing
+ * `---`. Claude-only — never call for other runtimes, which break on unknown
+ * frontmatter keys. Relocated verbatim from bin/install.js (#2875 Part 2).
+ */
+function injectDisallowedToolsFrontmatter(content, disallowedValue) {
+    const eol = /^---\r\n/.test(content) ? '\r\n' : '\n';
+    const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
+    const match = fmRe.exec(content);
+    if (!match)
+        return content; // no YAML frontmatter — leave unchanged
+    const fmBody = match[1]; // content between the two `---` lines
+    if (/^disallowedTools:/m.test(fmBody))
+        return content;
+    const openLen = 3 + eol.length; // "---" + eol
+    const closingStart = match.index + openLen + fmBody.length;
+    const before = content.slice(0, closingStart);
+    const after = content.slice(closingStart);
+    return `${before}disallowedTools: ${disallowedValue}${eol}${after}`;
+}
+// #767 — Read-only verifier/auditor agents get a Claude-Code disallowedTools deny-list.
+// Group A (pure read-only) deny Write,Edit,MultiEdit. Group B report-writers Write one
+// output file so they deny only Edit,MultiEdit. gsd-nyquist-auditor is intentionally
+// excluded (it legitimately uses Write AND Edit to create/patch test files). Relocated
+// verbatim from bin/install.js (#2875 Part 2) — single source of truth for both the
+// inline loop (which now requires this export) and the descriptor pipeline.
+const READONLY_AGENT_DISALLOWED_TOOLS = {
+    'gsd-plan-checker': 'Write, Edit, MultiEdit',
+    'gsd-integration-checker': 'Write, Edit, MultiEdit',
+    'gsd-ui-checker': 'Write, Edit, MultiEdit',
+    'gsd-verifier': 'Edit, MultiEdit',
+    'gsd-doc-verifier': 'Edit, MultiEdit',
+    'gsd-eval-auditor': 'Edit, MultiEdit',
+    'gsd-ui-auditor': 'Edit, MultiEdit',
+};
+/**
+ * Post-converter frontmatter-extensions step (#2875 Part 2 / ADR-1235 §1
+ * follow-up). Driven by the runtime descriptor's
+ * `hostBehaviors.agentFrontmatterExtensions` allow-list — Claude is its only
+ * declared consumer today (`agentFrontmatterExtensions: ["effort"]`).
+ * A runtime that does NOT declare the extension gets nothing injected (J3):
+ * OpenCode/Qwen/Hermes reject unknown frontmatter keys.
+ *
+ * Byte-identical to the inline agent loop's
+ * `if ((_hostBehaviors(runtime).agentFrontmatterExtensions || []).includes('effort'))`
+ * block (bin/install.js): both the effort injection AND the disallowedTools
+ * injection are gated behind the SAME `'effort'` extension flag — there is no
+ * separate `'disallowedTools'` extension key, mirroring the loop exactly.
+ *
+ * J2 (the trap row): when the resolved effort is `'inherit'`, NO `effort:`
+ * key is written at all — the absence of the key IS the behavior (#3533).
+ * Writing `effort: inherit` would be a regression that looks like success.
+ *
+ * @param content    agent .md content, already converter-transformed
+ * @param runtime    canonical runtime ID
+ * @param agentName  agent stem (from deriveAgentName), e.g. 'gsd-planner'
+ * @param targetDir  install root — resolves .planning/config.json + ~/.gsd/defaults.json
+ */
+function applyAgentFrontmatterExtensions(content, { runtime, agentName, targetDir }) {
+    const extensions = _hostBehaviors(runtime).agentFrontmatterExtensions || [];
+    if (!extensions.includes('effort'))
+        return content;
+    let result = content;
+    const effortCfg = readGsdEffectiveEffortConfig(targetDir ?? null);
+    const universalEffort = resolveInstallTimeEffort(effortCfg, agentName);
+    // #3533 (10d): 'inherit' means the effort: key must NOT exist — Claude Code
+    // then follows the session effort. The canonical source agents carry no
+    // effort key, so skipping injection is the whole job.
+    if (universalEffort !== 'inherit') {
+        const renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime(runtime, universalEffort).value;
+        result = injectEffortFrontmatter(result, renderedEffort);
+    }
+    const disallowedTools = READONLY_AGENT_DISALLOWED_TOOLS[agentName];
+    if (disallowedTools)
+        result = injectDisallowedToolsFrontmatter(result, disallowedTools);
+    return result;
+}
 /**
  * Apply Co-Authored-By attribution policy to file content.
  *   - null      -> remove the Co-Authored-By line and its preceding blank line
@@ -2628,15 +3292,25 @@ module.exports = {
     convertClaudeToAntigravityContent,
     convertClaudeCommandToAntigravitySkill,
     convertClaudeCommandToClaudeSkill,
+    // #2873 (4b): pure, scope-free transform — applied by the one call site
+    // that knows install scope (skillsKind's stage() in
+    // runtime-artifact-layout.cts), never inside convertClaudeCommandToClaudeSkill
+    // itself.
+    resolveSpecRootReference,
     convertClaudeCommandToKimiSkill,
     convertClaudeCommandToKimiCodeSkill,
     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,
@@ -2677,11 +3351,20 @@ module.exports = {
     convertClaudeAgentToCodebuddyAgent,
     convertClaudeAgentToClineAgent,
     convertClaudeAgentToCodexAgent,
+    // #2875 Part 2 (J10): Hermes named branding converter, generic underlying
+    // transform exported alongside it for direct reuse/testing.
+    convertClaudeAgentToHermesAgent,
+    applyAgentBrandingRewrites,
     // ADR-1239 / #2092 Phase B Upgrade 1: native .qwen/agents/*.md subagent
     // projection — registered by name so convertedAgentsKind's
     // conversionExports[converterName] dispatch (runtime-artifact-layout.cts)
     // can resolve it from capabilities/qwen/capability.json's agents kind.
     convertClaudeAgentToQwenAgent,
+    // #3384: ZCode agents are Claude-shaped but its dispatcher treats mcp__*
+    // tools grants as required MCP servers — registered by name for the same
+    // conversionExports[converterName] dispatch, resolved from
+    // capabilities/zcode/capability.json's agents kind.
+    convertClaudeAgentToZcodeAgent,
     // #1511 ADR-1508 Phase 2: rewrite engine deep seam
     // Low-level walkers (pathPrefix + attribution pre-resolved by caller):
     applyRuntimeContentRewritesInPlace,
@@ -2692,9 +3375,21 @@ module.exports = {
     // ADR-1235 §1: descriptor-driven agent cross-cutting
     applyAgentPathRewrites,
     normalizeAgentBodyForRuntime,
+    // #2875 Part 2: descriptor-driven agent frontmatter-extensions step + its
+    // single-sourced building blocks (also required back by bin/install.js so
+    // the inline loop and the descriptor pipeline resolve through the SAME
+    // code — no drift between the two byte-parity-gated pipelines).
+    deriveAgentName,
+    injectEffortFrontmatter,
+    injectDisallowedToolsFrontmatter,
+    READONLY_AGENT_DISALLOWED_TOOLS,
+    applyAgentFrontmatterExtensions,
     _computePathPrefix: computePathPrefix,
+    _restoreClaudeGlobalAtRefTilde: restoreClaudeGlobalAtRefTilde,
     _applyRuntimeRewrites,
     _stampNonClaudeRuntimeDefaults,
+    // #2652: registry-resolved dispatch isolation, mirroring routeDispatchIsolation
+    _negotiatedDispatchIsolation,
     // #1521: canonical non-Claude runtime list for test files and tooling
     NON_CLAUDE_RUNTIMES,
 };