@opengsd/gsd-core 1.15.0 → 1.16.0

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

@@ -33,11 +33,12 @@ 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 { getDirName, hostBehaviorsFor } = 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 frontmatter_fence_cjs_1 = require("./frontmatter-fence.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
@@ -93,24 +94,6 @@ function gsdVersion() {
         cachedVersion = resolveVersionFrom(__dirname);
     return cachedVersion;
 }
-/**
- * Host-specific install behaviors declared on the runtime descriptor
- * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors). Mirrors
- * bin/install.js's / install-engine.cts's `_hostBehaviors` (ADR-1239 / #2086
- * / #2092). Returns {} for runtimes that declare none, so every behavior
- * branch degrades to the generic path by default. Unlike the bin/install.js
- * and install-engine.cts variants, this module already imports
- * `capabilityRegistry` statically (see NON_CLAUDE_RUNTIMES below), so this
- * reads it directly rather than re-require()-ing inside a try/catch.
- */
-function _hostBehaviors(runtime) {
-    return ((capabilityRegistry &&
-        capabilityRegistry.runtimes &&
-        capabilityRegistry.runtimes[runtime] &&
-        capabilityRegistry.runtimes[runtime].runtime &&
-        capabilityRegistry.runtimes[runtime].runtime.hostBehaviors) ||
-        {});
-}
 /**
  * Public accessor for the `hostBehaviors.agentFileExtension` descriptor field
  * (ADR-1239 / #2099 / #2103). Returns the runtime's declared agent-file
@@ -122,7 +105,7 @@ function _hostBehaviors(runtime) {
  * duplicating a hardcoded `runtime === 'copilot'` check (#2103 fold).
  */
 function agentFileExtensionFor(runtime) {
-    const ext = _hostBehaviors(runtime).agentFileExtension;
+    const ext = hostBehaviorsFor(runtime).agentFileExtension;
     return typeof ext === 'string' ? ext : undefined;
 }
 const colorNameToHex = {
@@ -485,7 +468,7 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
     // Hermes' SKILL.md spec lists `version` as a required frontmatter field.
     // Track GSD's package version so Hermes' skill_view() reports a stable
     // identifier per install.
-    if (runtime === 'hermes') {
+    if (hostBehaviorsFor(runtime).skillFrontmatterVersion) {
         const version = gsdVersion();
         if (version)
             fm += `version: ${yamlQuote(version)}\n`;
@@ -495,7 +478,7 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
     // runtimes that declare the flag so Claude/Hermes skill frontmatter is
     // unchanged (they ignore the field, but we keep their output byte-stable).
     // skillName is the `gsd-<stem>` dir name. (ADR-1239 / #2092)
-    if (_hostBehaviors(runtime).skillPriorityFrontmatter) {
+    if (hostBehaviorsFor(runtime).skillPriorityFrontmatter) {
         const stem = typeof skillName === 'string' && skillName.startsWith('gsd-')
             ? skillName.slice(4)
             : skillName;
@@ -730,10 +713,13 @@ function appendAgentTools(content, grants) {
         return content;
     const eol = content.includes('\r\n') ? '\r\n' : '\n';
     const lines = content.split(eol);
-    if (lines[0] !== '---')
+    // The block is the one the one fence owner finds; `frontmatterEnd` is its closing fence's
+    // line index in `lines`.
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return content;
-    const frontmatterEnd = lines.indexOf('---', 1);
-    if (frontmatterEnd === -1)
+    const frontmatterEnd = content.slice(0, fence.closingStart).split(eol).length - 1;
+    if (frontmatterEnd < 1)
         return content;
     const toolsIndex = lines.findIndex((line, index) => index < frontmatterEnd && /^tools:[ \t]*(.*)$/.test(line));
     if (toolsIndex === -1)
@@ -1080,17 +1066,19 @@ function yamlIdentifier(value) {
     }
     return yamlQuote(text);
 }
+/**
+ * The frontmatter YAML (trimmed) and everything after the closing fence line's text, for the
+ * block the one fence owner (`locateFrontmatterFence`) finds — so a `---` inside a value (a
+ * description that mentions `a---b`) cannot end the block early.
+ */
 function extractFrontmatterAndBody(content) {
-    if (!content.startsWith('---')) {
-        return { frontmatter: null, body: content };
-    }
-    const endIndex = content.indexOf('---', 3);
-    if (endIndex === -1) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed) {
         return { frontmatter: null, body: content };
     }
     return {
-        frontmatter: content.substring(3, endIndex).trim(),
-        body: content.substring(endIndex + 3),
+        frontmatter: content.slice(fence.openEnd, fence.bodyEnd).trim(),
+        body: content.slice(fence.closingFenceEnd),
     };
 }
 function extractFrontmatterField(frontmatter, fieldName) {
@@ -1539,7 +1527,7 @@ function convertClaudeCommandToTraeSkill(content, skillName) {
     // is not formally documented (thin SPA docs) — descriptor-driven, single
     // fixed GSD-side value (runtime.hostBehaviors.soloStageMetadata), inferred/
     // best-effort.
-    const soloStage = _hostBehaviors('trae').soloStageMetadata;
+    const soloStage = hostBehaviorsFor('trae').soloStageMetadata;
     if (soloStage)
         fm += `stage: ${soloStage}\n`;
     fm += '---';
@@ -1955,17 +1943,11 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
     convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
     // Runtime-neutral agent name replacement (#766)
     convertedContent = neutralizeAgentReferences(convertedContent, 'AGENTS.md');
-    // Check if content has frontmatter
-    if (!convertedContent.startsWith('---')) {
-        return convertedContent;
-    }
-    // Find the end of frontmatter
-    const endIndex = convertedContent.indexOf('---', 3);
-    if (endIndex === -1) {
+    // The frontmatter block, as the one fence owner finds it (none → nothing to convert).
+    const { frontmatter, body } = extractFrontmatterAndBody(convertedContent);
+    if (frontmatter === null) {
         return convertedContent;
     }
-    const frontmatter = convertedContent.substring(3, endIndex).trim();
-    const body = convertedContent.substring(endIndex + 3);
     // Parse frontmatter line by line (simple YAML parsing)
     const lines = frontmatter.split('\n');
     const newLines = [];
@@ -2121,17 +2103,11 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
     convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
     // Runtime-neutral agent name replacement (#766)
     convertedContent = neutralizeAgentReferences(convertedContent, 'AGENTS.md');
-    // Check if content has frontmatter
-    if (!convertedContent.startsWith('---')) {
-        return convertedContent;
-    }
-    // Find the end of frontmatter
-    const endIndex = convertedContent.indexOf('---', 3);
-    if (endIndex === -1) {
+    // The frontmatter block, as the one fence owner finds it (none → nothing to convert).
+    const { frontmatter, body } = extractFrontmatterAndBody(convertedContent);
+    if (frontmatter === null) {
         return convertedContent;
     }
-    const frontmatter = convertedContent.substring(3, endIndex).trim();
-    const body = convertedContent.substring(endIndex + 3);
     // Parse frontmatter line by line (simple YAML parsing)
     const lines = frontmatter.split('\n');
     const newLines = [];
@@ -2526,7 +2502,7 @@ function convertClaudeAgentToTraeAgent(content) {
  * forms to avoid double-rewriting the same substring.
  */
 function convertClaudeAgentToQwenAgent(content) {
-    const _b = _hostBehaviors('qwen').brandingRewrites || {};
+    const _b = hostBehaviorsFor('qwen').brandingRewrites || {};
     let converted = content;
     if (_b['CLAUDE.md'])
         converted = converted.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
@@ -2591,18 +2567,14 @@ function convertClaudeAgentToZcodeAgent(content) {
     // present. The unchanged scan below still preserves byte-identical content.
     if (!content.includes('mcp__') && !content.includes('\\'))
         return content;
-    const lines = content.split('\n');
-    if (lines[0] !== '---')
+    // The block is the one the one fence owner finds; unterminated (or absent) → leave verbatim.
+    // The rewrite below re-joins lines on '\n', so a CRLF block is left verbatim too rather than
+    // given mixed line endings.
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed || fence.eol !== '\n')
         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 lines = content.split('\n');
+    const fmEnd = content.slice(0, fence.closingStart).split('\n').length - 1;
     const out = [];
     let changed = false;
     let i = 1;
@@ -2699,12 +2671,12 @@ function convertClaudeAgentToClineAgent(content) {
  * 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)`
+ * Byte-identical to the inline loop's `else if (hostBehaviorsFor(runtime).brandingRewrites)`
  * branch, including plain (non-word-boundary) `.replace(/\bClaude Code\b/g, ...)`
  * semantics — J9.
  */
 function applyAgentBrandingRewrites(content, runtime) {
-    const _b = _hostBehaviors(runtime).brandingRewrites;
+    const _b = hostBehaviorsFor(runtime).brandingRewrites;
     if (!_b)
         return content;
     let converted = content;
@@ -2890,7 +2862,7 @@ function projectRelativePrefixFromProjectRoot(projectRoot, resolvedTarget) {
  * directory in a project-relative include: that directory was never created.
  */
 function localIncludeDirName(runtime) {
-    return _hostBehaviors(runtime).localTargetIsProjectRoot === true ? undefined : getDirName(runtime);
+    return hostBehaviorsFor(runtime).localTargetIsProjectRoot === true ? undefined : getDirName(runtime);
 }
 /**
  * #4377: the project-relative prefix for a local install, or `''` when the
@@ -3194,11 +3166,16 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
     // #1521: stamp runtime identity + use_worktrees=false for every non-Claude runtime
     // before brand-specific path rewrites, so the replace operates on the pristine
     // source line and is idempotent regardless of subsequent path substitutions.
-    if (runtime !== 'claude') {
+    // #5169: the descriptor declares which hosts skip the stamp
+    // (`hostBehaviors.skipRuntimeDefaultsStamp`) and which rewrite profile applies
+    // (`hostBehaviors.contentRewriteProfile`). The switch below is keyed by PROFILE
+    // name, not runtime id, so two hosts that share a body share one case.
+    const rewriteBehaviors = hostBehaviorsFor(runtime);
+    if (!rewriteBehaviors.skipRuntimeDefaultsStamp) {
         content = _stampNonClaudeRuntimeDefaults(content, runtime);
     }
-    switch (runtime) {
-        case 'codex':
+    switch (rewriteBehaviors.contentRewriteProfile) {
+        case 'slash-own-tilde':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3206,7 +3183,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             // #1515 stamp moved to _stampNonClaudeRuntimeDefaults (#1521 generalisation).
             content = processAttribution(content, attribution);
             break;
-        case 'cline':
+        case 'slash-bare-own-tilde':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3218,7 +3195,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = content.replace(/\$HOME\/\.cline\b/g, normalizedPathPrefix);
             content = processAttribution(content, attribution);
             break;
-        case 'cursor':
+        case 'slash-lookahead-own-tilde':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3228,7 +3205,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = content.replace(/~\/\.cursor\//g, pathPrefix);
             content = processAttribution(content, attribution);
             break;
-        case 'windsurf': {
+        case 'slash-lookahead-nested-own-devin': {
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3244,7 +3221,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = processAttribution(content, attribution);
             break;
         }
-        case 'augment': {
+        case 'slash-lookahead-own-derived': {
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3262,7 +3239,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = processAttribution(content, attribution);
             break;
         }
-        case 'trae':
+        case 'slash-bare-own-derived':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3275,7 +3252,7 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = content.replace(new RegExp('~/' + (0, pattern_cjs_1.escapeRegex)(dirName) + '/', 'g'), pathPrefix);
             content = processAttribution(content, attribution);
             break;
-        case 'codebuddy':
+        case 'slash-bare-own-tilde-bare':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3288,13 +3265,14 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = content.replace(/\$HOME\/\.codebuddy\b/g, normalizedPathPrefix);
             content = processAttribution(content, attribution);
             break;
-        case 'copilot':
+        case 'attribution-only':
             content = processAttribution(content, attribution);
             break;
-        case 'antigravity':
-            content = processAttribution(content, attribution);
-            break;
-        case 'claude':
+        // claude and zcode share this profile. #4002: ZCode is a Claude-Code-shaped
+        // host (dot-home `.zcode`, `@~`-ref expansion, `~/.zcode/...` documented
+        // paths) whose commands install with `converter: null` — this pass is their
+        // only chance to receive runtime-correct paths, including the tilde restore.
+        case 'slash-tilde-restore':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3308,37 +3286,15 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
         // brand VALUES (CLAUDE.md/Claude Code/.claude/ replacements) now read from
         // runtime.hostBehaviors.brandingRewrites instead of hardcoded literals.
         // EXACT regexes/order preserved — only the replacement values changed.
-        case 'qwen': {
+        // qwen and hermes share this profile; their own dot-dir is derived from the
+        // descriptor's `localConfigDir` (`getDirName`) rather than spelled per host.
+        case 'branded-lookahead-own-derived': {
             // Guarded (post-review #2092): brandingRewrites is undefined if the
             // capability registry fails to load — degrade closed (skip the
             // brand-literal replacements, still apply the non-branding path
             // rewrites below) instead of throwing on `_b['CLAUDE.md']`.
-            const _b = _hostBehaviors(runtime).brandingRewrites;
-            if (_b) {
-                content = content.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
-                // #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);
-            content = content.replace(/~\/\.qwen\//g, pathPrefix);
-            content = content.replace(/\$HOME\/\.qwen\//g, pathPrefix);
-            content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/~\/\.qwen(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/\$HOME\/\.qwen(?![\w-])/g, normalizedPathPrefix);
-            if (_b) {
-                content = content.replace(/\.claude\//g, _b['.claude/']);
-            }
-            content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-            content = content.replace(/\.\/\.qwen\//g, `./${dirName}/`);
-            content = processAttribution(content, attribution);
-            break;
-        }
-        case 'hermes': {
-            // Guarded (post-review #2092): see qwen case above — same degrade-closed
-            // rationale.
-            const _b = _hostBehaviors(runtime).brandingRewrites;
+            const _b = rewriteBehaviors.brandingRewrites;
+            const _own = (0, pattern_cjs_1.escapeRegex)(dirName);
             if (_b) {
                 content = content.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
                 // #2284(b): skips <runtime_compatibility> comparison-table content (protected region).
@@ -3346,21 +3302,21 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             }
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-            content = content.replace(/~\/\.hermes\//g, pathPrefix);
-            content = content.replace(/\$HOME\/\.hermes\//g, pathPrefix);
+            content = content.replace(new RegExp('~/' + _own + '/', 'g'), pathPrefix);
+            content = content.replace(new RegExp('\\$HOME/' + _own + '/', 'g'), pathPrefix);
             content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
             content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/~\/\.hermes(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/\$HOME\/\.hermes(?![\w-])/g, normalizedPathPrefix);
+            content = content.replace(new RegExp('~/' + _own + '(?![\\w-])', 'g'), normalizedPathPrefix);
+            content = content.replace(new RegExp('\\$HOME/' + _own + '(?![\\w-])', 'g'), normalizedPathPrefix);
             if (_b) {
                 content = content.replace(/\.claude\//g, _b['.claude/']);
             }
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-            content = content.replace(/\.\/\.hermes\//g, `./${dirName}/`);
+            content = content.replace(new RegExp('\\./' + _own + '/', 'g'), `./${dirName}/`);
             content = processAttribution(content, attribution);
             break;
         }
-        case 'kimi':
+        case 'slash-bare':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
@@ -3369,22 +3325,8 @@ function _applyRuntimeRewritesInner(content, runtime, pathPrefix, isGlobal = fal
             content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
             content = processAttribution(content, attribution);
             break;
-        case 'zcode':
-            // #4002: ZCode is a Claude-Code-shaped host (dot-home `.zcode`, `@~`-ref
-            // expansion, `~/.zcode/...` documented paths) whose commands install with
-            // `converter: null` — this pass is their only chance to receive
-            // runtime-correct paths. Same shape as `claude`, including the tilde
-            // restore: the tilde form is what ZCode expands and what its docs use.
-            // `${_GSD_RUNTIME_ROOT}/.claude/…` matches none of these regexes and
-            // survives as the project-local fallback, exactly as on every sibling.
-            content = content.replace(/~\/\.claude\//g, pathPrefix);
-            content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-            content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-            content = restoreClaudeGlobalAtRefTilde(content, pathPrefix);
-            content = processAttribution(content, attribution);
-            break;
         default:
-            // Unknown runtime — no rewrites (OpenCode/Kilo handled by their own install path).
+            // No profile declared — no rewrites (OpenCode/Kilo handled by their own install path).
             break;
     }
     return content;
@@ -3450,7 +3392,7 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
             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.
-            const _cmdConv = _hostBehaviors(runtime).commandBodyConverter;
+            const _cmdConv = hostBehaviorsFor(runtime).commandBodyConverter;
             if (_cmdConv && COMMAND_BODY_CONVERTERS[_cmdConv]) {
                 content = COMMAND_BODY_CONVERTERS[_cmdConv](content);
             }
@@ -3539,7 +3481,7 @@ function rewriteStagedSkillBodies(stagedDir, opts) {
     // 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) {
+    if (hostBehaviorsFor(runtime).specRootSkillPass && isGlobal) {
         applySpecRootReferenceToStagedSkills(stagedDir);
     }
 }
@@ -3591,7 +3533,7 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
  * @param cmdNames  gsd command names from readGsdCommandNames()
  */
 function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
-    if (_hostBehaviors(runtime).hyphenNameAgentBody !== true)
+    if (hostBehaviorsFor(runtime).hyphenNameAgentBody !== true)
         return content;
     return transformContentToHyphen(content, cmdNames);
 }
@@ -3621,7 +3563,7 @@ function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
  * @returns content with path-prefix rewrites applied (or unchanged for noPathRewrite runtimes, e.g. copilot)
  */
 function applyAgentPathRewrites(content, runtime, pathPrefix) {
-    if (_hostBehaviors(runtime).noPathRewrite === true)
+    if (hostBehaviorsFor(runtime).noPathRewrite === true)
         return content;
     // #4377: the agents pipeline is the third emit path that substitutes this
     // prefix (skills/commands via _applyRuntimeRewrites, the gsd-core spec tree
@@ -3663,7 +3605,7 @@ function applyAgentPathRewritesInner(content, runtime, pathPrefix) {
     // 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') {
+    if (hostBehaviorsFor(runtime).restoreAtRefTildeInAgents) {
         content = restoreClaudeGlobalAtRefTilde(content, normalizedPathPrefix);
     }
     return content;
@@ -3687,8 +3629,8 @@ function deriveAgentName(fileName) {
  * `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).
+ *   - Reads the block the one fence owner (`locateFrontmatterFence`) finds, and
+ *     its EOL (CRLF if the opening `---` 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,
@@ -3697,19 +3639,15 @@ function deriveAgentName(fileName) {
  *   - 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)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return content; // no YAML frontmatter — leave unchanged
-    const fmBody = match[1]; // content between the two `---` lines
+    const fmBody = content.slice(fence.openEnd, fence.closingStart); // content between the two fences
     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}`;
+    const before = content.slice(0, fence.closingStart);
+    const after = content.slice(fence.closingStart);
+    return `${before}effort: ${effortValue}${fence.eol}${after}`;
 }
 /**
  * #767 — Inject `disallowedTools: <value>` into the YAML frontmatter of a
@@ -3719,19 +3657,15 @@ function injectEffortFrontmatter(content, effortValue) {
  * 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)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return content; // no YAML frontmatter — leave unchanged
-    const fmBody = match[1]; // content between the two `---` lines
+    const fmBody = content.slice(fence.openEnd, fence.closingStart); // content between the two fences
     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}`;
+    const before = content.slice(0, fence.closingStart);
+    const after = content.slice(fence.closingStart);
+    return `${before}disallowedTools: ${disallowedValue}${fence.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
@@ -3757,7 +3691,7 @@ const READONLY_AGENT_DISALLOWED_TOOLS = {
  * OpenCode/Qwen/Hermes reject unknown frontmatter keys.
  *
  * Byte-identical to the inline agent loop's
- * `if ((_hostBehaviors(runtime).agentFrontmatterExtensions || []).includes('effort'))`
+ * `if ((hostBehaviorsFor(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.
@@ -3772,7 +3706,7 @@ const READONLY_AGENT_DISALLOWED_TOOLS = {
  * @param targetDir  install root — resolves .planning/config.json + ~/.gsd/defaults.json
  */
 function applyAgentFrontmatterExtensions(content, { runtime, agentName, targetDir }) {
-    const extensions = _hostBehaviors(runtime).agentFrontmatterExtensions || [];
+    const extensions = hostBehaviorsFor(runtime).agentFrontmatterExtensions || [];
     if (!extensions.includes('effort'))
         return content;
     let result = content;

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -10,6 +10,7 @@
 const _require = require;
 const path = _require('node:path');
 const { tryWithinRootLexical } = _require('./security.cjs');
+const { hostBehaviorsFor } = _require('./runtime-name-policy.cjs');
 // #2870: InstallScope is owned by install-scope.cts, not re-declared here.
 // `isGlobalScope` centralizes the `scope === 'global'` boolean projection
 // this module needs at `_computePathPrefix`'s `isGlobal: boolean` boundary
@@ -90,7 +91,7 @@ function createRuntimeArtifactInstallPlan(args) {
     // `undefined` here) — `isGlobalScope` projects it to the boolean
     // `_computePathPrefix`'s existing `isGlobal: boolean` API requires.
     const isGlobal = (0, install_scope_cjs_1.isGlobalScope)(scope);
-    const isOpencode = layout.runtime === 'opencode';
+    const isOpencode = hostBehaviorsFor(layout.runtime).opencodePathPrefix === true;
     const isWindowsHost = (platform ?? process.platform) === 'win32';
     // #4377: descriptor-derived local dir name, so an opted-in local install
     // emits a project-relative prefix instead of this checkout's absolute path.

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

@@ -957,4 +957,60 @@ function resolveTriggerSurface(runtime, scopes, opts) {
     }
     return surfaces;
 }
-module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot, resolveTriggerSurface, isNamespacedByDir, composeCommandFilename };
+// ---------------------------------------------------------------------------
+// The advertised "next step" command (#5215, ADR-5057 §5 Phase 12).
+//
+// What the installer tells a user to run is a projection of what the runtime
+// registered: the `new-project` trigger the Trigger Surface resolves for the
+// install scope. It is never a per-runtime literal, so a runtime that registers
+// no such trigger (pi's native extension registers only `/gsd`; windsurf's
+// global layout registers nothing) cannot be told to run one (#4567).
+// ---------------------------------------------------------------------------
+/** The cross-agent default for an id GSD cannot know (ADR-5057 §5 Phase 10 amendment). */
+const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
+/**
+ * How a host invokes a registered trigger. Presentation only — whether the
+ * trigger exists is decided by the registered surface, not by this table. A
+ * runtime absent here is invoked as `/<trigger>`.
+ */
+const TRIGGER_INVOCATION = {
+    codex: (trigger) => `$${trigger}`,
+    cursor: (trigger) => `${trigger} (mention the skill name)`,
+    kimi: (trigger) => `/skill:${trigger}`,
+};
+/**
+ * The command a native-extension runtime registers instead of per-workflow
+ * triggers: the extension file's stem as a slash command (pi's `gsd.js`
+ * registers `/gsd`; pinned by tests/advertised-command-parity.test.cjs against
+ * the extension itself). `null` for a runtime with no native plugin.
+ */
+function nativePluginCommand(runtime) {
+    const descriptor = getTriggerRegistry().runtimes[runtime]?.runtime;
+    const file = descriptor?.hostBehaviors?.nativePlugin?.file;
+    if (typeof file !== 'string' || file.length === 0)
+        return null;
+    const stem = file.replace(/\.[^.]+$/, '');
+    return stem.length > 0 ? `/${stem}` : null;
+}
+/**
+ * The command the installer advertises for starting a project, generated from
+ * the registered trigger surface of `runtime` in `scope`. `unregistered` means
+ * the runtime registers no `new-project` trigger there (`nativeCommand` names
+ * what a native-extension runtime registers instead). An empty or unregistered
+ * id keeps the documented cross-agent default: it names a runtime GSD cannot
+ * know, so no surface exists to project from. Membership is decided up front,
+ * so an error inside the surface resolution is a bug and propagates.
+ */
+function resolveAdvertisedNewProject(runtime, scope) {
+    const known = Boolean(runtime) && Object.prototype.hasOwnProperty.call(getTriggerRegistry().runtimes, runtime);
+    if (!known)
+        return { kind: 'command', command: DEFAULT_NEW_PROJECT_COMMAND };
+    const registered = resolveTriggerSurface(runtime, [scope], { stems: ['new-project'] })[0];
+    if (!registered)
+        return { kind: 'unregistered', nativeCommand: nativePluginCommand(runtime) };
+    const render = Object.prototype.hasOwnProperty.call(TRIGGER_INVOCATION, runtime)
+        ? TRIGGER_INVOCATION[runtime]
+        : (trigger) => `/${trigger}`;
+    return { kind: 'command', command: render(registered.trigger) };
+}
+module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot, resolveTriggerSurface, resolveAdvertisedNewProject, isNamespacedByDir, composeCommandFilename };