@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -21,12 +21,35 @@ 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 frontmatterModule = require("./frontmatter.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
@@ -270,11 +293,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}`);
 }
 /**
@@ -367,16 +387,6 @@ function skillFrontmatterName(skillDirName) {
     // Return the hyphen form as-is (gsd-<cmd>) — canonical since #2808.
     return skillDirName;
 }
-function normalizeClaudeSkillEffort(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.
  * Per the Qwen skills spec (qwen-code/docs/users/features/skills.md, verified
@@ -431,10 +441,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 = '';
@@ -474,19 +487,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('/'))
@@ -502,7 +596,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');
@@ -754,7 +848,8 @@ function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSuba
 /**
  * Apply Antigravity-specific content conversion — path replacement + command name conversion.
  * Path mappings depend on install mode:
- *   Global: ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agents/
+ *   Global: ~/.claude/skills/ → ~/.gemini/config/skills/ (#3738),
+ *          ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agents/
  *   Local:  ~/.claude/ → .agents/, ./.claude/ → ./.agents/
  * Applied to ALL Antigravity content (skills, agents, engine files).
  * @param {string} content - Source content to convert
@@ -763,6 +858,18 @@ function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSuba
 function convertClaudeToAntigravityContent(content, isGlobal = false) {
     let c = content;
     if (isGlobal) {
+        // #3738: global skills install under ~/.gemini/config/skills (the dir AGY
+        // scans for global discovery), so skills-path references must divert there
+        // — BEFORE the configHome rewrite below, which is correct for gsd-core
+        // runtime-file references (settings, workflows, VERSION) but wrong for the
+        // skills dir itself.
+        c = c.replace(/\$HOME\/\.claude\/skills\//g, '$HOME/.gemini/config/skills/');
+        c = c.replace(/~\/\.claude\/skills\//g, '~/.gemini/config/skills/');
+        // Bare skills form (no trailing slash) — must also precede the generic
+        // slash rule, which would otherwise divert it to the retired configHome
+        // path ($HOME/.gemini/antigravity/skills).
+        c = c.replace(/\$HOME\/\.claude\/skills\b/g, '$HOME/.gemini/config/skills');
+        c = c.replace(/~\/\.claude\/skills\b/g, '~/.gemini/config/skills');
         c = c.replace(/\$HOME\/\.claude\//g, '$HOME/.gemini/antigravity/');
         c = c.replace(/~\/\.claude\//g, '~/.gemini/antigravity/');
         // Bare form (no trailing slash) — must come after slash form to avoid double-replace
@@ -1533,7 +1640,7 @@ 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,
@@ -1609,7 +1716,26 @@ function neutralizeAgentReferences(content, instructionFile) {
     c = c.replace(/Do NOT load full `AGENTS\.md` files[^\n]*/g, '');
     return c;
 }
-function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
+/**
+ * Render one frontmatter `key: value` line whose value came from user config.
+ *
+ * #3706: both `model:` and `variant:` interpolate a value read from
+ * `.planning/config.json` / `~/.gsd/defaults.json`. Raw interpolation lets a value
+ * containing a newline inject additional TOP-LEVEL frontmatter keys into the
+ * generated agent file — proven by execution during the #3705 security review
+ * (`"sonnet\ntools: [\"*\"]\npermission: bypass"` produced two extra keys).
+ *
+ * That sink predates #3706, but this change adds a SECOND write to it, so it is
+ * closed here rather than doubled. Both the decision and the escaping live in
+ * frontmatter.cts so there is exactly one set of YAML scalar rules; a value that
+ * round-trips bare is still emitted bare, so generated files do not churn.
+ */
+function frontmatterScalar(key, value) {
+    return frontmatterModule.agentScalarNeedsDoubleQuoting(value)
+        ? `${key} "${frontmatterModule.escapeDoubleQuotedScalar(value)}"`
+        : `${key} ${value}`;
+}
+function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null, variant = null } = {}) {
     // Replace tool name references in content (applies to all files)
     let convertedContent = content;
     convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
@@ -1734,7 +1860,23 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
         // respected on OpenCode (which uses static agent frontmatter, not inline
         // Task() model parameters). See #2256.
         if (modelOverride) {
-            newLines.push(['model:', modelOverride].join(' '));
+            newLines.push(frontmatterScalar('model:', modelOverride));
+        }
+        // #3706: deliver the RESOLVED reasoning effort to the spawned subagent.
+        // `query resolve-model` reported an effort that never reached OpenCode, so
+        // every subagent ran at whatever opencode.jsonc defaults the model to — for
+        // a custom provider commonly the most expensive setting.
+        //
+        // OpenCode ONLY: `EFFORT_ARGV` declares surfaces for claude/opencode/codex
+        // and NO kilo entry, so the Kilo converter below deliberately does not emit
+        // this. Unlike the model side — where #2794 J8 requires kilo and opencode to
+        // resolve identically — there is no kilo effort surface to render into, and
+        // inventing one would emit a key that runtime never documented.
+        //
+        // Omitted entirely when absent, per #1156's rule for `model: inherit`:
+        // never an empty or sentinel value, let the runtime use its own default.
+        if (variant) {
+            newLines.push(frontmatterScalar('variant:', variant));
         }
     }
     // For commands: add tools object if we had allowed-tools or tools
@@ -1906,7 +2048,7 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
         // model emission exactly (#2093 UPGRADE 2 / ADR-1239; Kilo is an OpenCode
         // fork with the same static-frontmatter model constraint). See #2256.
         if (modelOverride) {
-            newLines.push(['model:', modelOverride].join(' '));
+            newLines.push(frontmatterScalar('model:', modelOverride));
         }
         newLines.push(...buildKiloAgentPermissionBlock(agentTools));
     }
@@ -2188,6 +2330,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);
@@ -2208,6 +2450,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
@@ -2320,20 +2604,151 @@ 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');
+    // Function replacement, not a string. A string replacement treats `$&` and the
+    // backtick-dollar form in the SUBSTITUTION as special patterns, so a --config-dir
+    // containing either corrupts output: `$HOME/.cl$&ude/` yielded
+    // `@~/.cl@$HOME/.cl$&ude/ude/x`, and the backtick form silently DROPPED text.
+    // Pre-existing, and #3719 adds a THIRD call site to this sink — which is how the
+    // previous two came to share the defect in the first place.
+    return content.replace(atRefRe, () => `@${tildeEquivalent}`);
+}
 /**
  * Apply the per-runtime rewrite table to a single content string.
  * Relocated from bin/install.js `_applyRuntimeRewrites`.
@@ -2410,7 +2825,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);
@@ -2428,7 +2843,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':
@@ -2454,6 +2869,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
@@ -2541,18 +2960,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);
             }
         }
     };
@@ -2577,14 +2996,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.
@@ -2592,18 +3011,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.
  *
@@ -2620,16 +3073,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.
@@ -2649,11 +3116,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 });
@@ -2709,11 +3179,165 @@ function applyAgentPathRewrites(content, runtime, pathPrefix) {
     const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-    content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-    content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
+    // #3719 review (MAJOR): a bare `\b` is satisfied by ANY non-word character,
+    // including '-' — for a --config-dir whose name EXTENDS '.claude' (e.g.
+    // '.claude-work'), this re-matched the '.claude' PREFIX of the emitted
+    // '.claude-work' path and corrupted it to '.claude-work-work'. Guard with
+    // the SAME negative-lookahead convention already used at
+    // copyWithPathReplacement's call site (bin/install.js:7729-7730).
+    content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+    content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+    // #3719: the THIRD emit path that needed this restore. #3133 added it to the
+    // skill/command pipeline (`_applyRuntimeRewrites` case 'claude') and #3544 to
+    // bin/install.js's spec-tree copy; the agents pipeline never got it, so every
+    // `@~/.claude/...` include in a global Claude install shipped as `@$HOME/...`
+    // and resolved to NOTHING (27 of 34 emitted agents, 103 lines).
+    //
+    // Guarded on `claude` for the same reason the sibling call site lives inside
+    // `case 'claude'`: the helper self-guards only on the `$HOME` PREFIX, and every
+    // runtime's global prefix is a `$HOME` form (`$HOME/.cursor/`, ...), so an
+    // unguarded call would rewrite `@`-refs for runtimes whose resolver has no
+    // documented `~` expansion at all.
+    //
+    // Passed the NORMALIZED prefix, not `pathPrefix`. The two word-boundary
+    // replaces above emit the trailing-slash-free form, and the helper's regex is
+    // anchored to the exact prefix string it is handed — so `restore(pathPrefix)`
+    // fixes `@$HOME/.claude/x` and leaves a bare `@$HOME/.claude` broken. The
+    // normalized form is a PREFIX of both, so one call covers both.
+    if (runtime === 'claude') {
+        content = restoreClaudeGlobalAtRefTilde(content, normalizedPathPrefix);
+    }
     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;
+        // #3007: `value` is `string | null` — a rejected/unrenderable level (e.g.
+        // 'ultra', or a catalog with no advertised level at or above the request)
+        // renders null. Same posture as the 'inherit' case above: omit the key
+        // entirely rather than writing a literal `effort: null`, so the host
+        // falls back to its own default instead of failing to parse.
+        if (renderedEffort !== null) {
+            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
@@ -2756,6 +3380,11 @@ 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,
@@ -2810,11 +3439,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,
@@ -2825,9 +3463,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,
 };