@opengsd/gsd-core 1.7.0-rc.5 → 1.7.0

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

@@ -26,6 +26,7 @@ const { readGsdCommandNames, transformContentToHyphen } = commandRoster;
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const { getDirName } = runtimeNamePolicy;
 const capabilityRegistry = require("./capability-registry.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // #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
@@ -66,6 +67,38 @@ 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
+ * destination-suffix rename target (e.g. copilot's `.agent.md`), or
+ * `undefined` when the runtime declares none (the generic no-rename
+ * default). Exported so callers outside this module (surface.cts's
+ * `_syncGsdDir`) can derive the SAME rename decision as
+ * install-engine.cts's staged-copy loop from ONE descriptor read, instead of
+ * duplicating a hardcoded `runtime === 'copilot'` check (#2103 fold).
+ */
+function agentFileExtensionFor(runtime) {
+    const ext = _hostBehaviors(runtime).agentFileExtension;
+    return typeof ext === 'string' ? ext : undefined;
+}
 const colorNameToHex = {
     cyan: '#00FFFF',
     red: '#FF0000',
@@ -412,10 +445,12 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
         if (version)
             fm += `version: ${yamlQuote(version)}\n`;
     }
-    // #778 (b) — Qwen-only numeric priority for /skills ordering. Scoped to qwen
-    // 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.
-    if (runtime === 'qwen') {
+    // #778 (b) — numeric priority for /skills ordering, declared on the runtime
+    // descriptor (runtime.hostBehaviors.skillPriorityFrontmatter). Scoped to
+    // 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) {
         const stem = typeof skillName === 'string' && skillName.startsWith('gsd-')
             ? skillName.slice(4)
             : skillName;
@@ -465,6 +500,14 @@ function convertGsdCommandReferencesToKimiSkillInvocations(content, cmdNames) {
         .replace(colonPattern, (_, cmd) => `/skill:gsd-${cmd}`)
         .replace(hyphenPattern, (_, cmd) => `/skill:gsd-${cmd}`);
 }
+// DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
+// convertClaudeCommandToKimiSkill (kept for bin/install.js's own
+// module-level export/test surface; dead for the live skills-install path,
+// which routes here via install-engine.cts's SKILLS_CONVERTER_REGISTRY
+// through the kimi capability descriptor's artifactLayout
+// `converter: "convertClaudeCommandToKimiSkill"`). Neither copy re-exports
+// the other — mirror any behavior change into both. Guarded by the
+// output-parity test in tests/runtime-converters.test.cjs (#2095).
 function convertClaudeCommandToKimiSkill(content, skillName, _runtime = null, cmdNames = null) {
     const { frontmatter, body } = extractFrontmatterAndBody(content);
     const kimiSkillName = normalizeKimiSkillName(skillName);
@@ -592,6 +635,15 @@ function buildKimiSubagentYaml({ name, description, tools }) {
     pushKimiToolsYaml(lines, 2, tools);
     return `${lines.join('\n')}\n`;
 }
+// DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
+// buildKimiAgentArtifacts (kept for bin/install.js's own module-level
+// export/test surface; dead for the live install path, which routes here via
+// runtime-artifact-layout.cts's kimiAgentsKind through a dynamic
+// `conversionExports['buildKimiAgentArtifacts']` lookup against this
+// compiled module). Neither copy re-exports the other — mirror any behavior
+// change into both, including the kimi_cli.tools.agent:Agent grant that
+// enables background dispatch (#2095 Upgrade 2). Guarded by the
+// output-parity test in tests/runtime-converters.test.cjs (#2095).
 function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSubagents = null, } = {}) {
     const diagnostics = [];
     const rootSource = parseKimiAgentSource(rootAgent) || { path: null, content: '' };
@@ -971,6 +1023,10 @@ function convertClaudeToAugmentMarkdown(content) {
     converted = converted.replace(/\bClaude Code\b/g, 'Augment');
     return converted;
 }
+// #2097 (ADR-1239): command-body converters selected by descriptor
+// (runtime.hostBehaviors.commandBodyConverter) instead of a runtime-name
+// branch. Degrade-closed: unknown/absent name → no conversion.
+const COMMAND_BODY_CONVERTERS = { convertClaudeToAugmentMarkdown };
 function getAugmentSkillAdapterHeader(skillName) {
     return `<augment_skill_adapter>
 ## A. Skill Invocation
@@ -1045,6 +1101,12 @@ function convertClaudeToTraeMarkdown(content) {
     converted = converted.replace(/\bClaude Code\b/g, 'Trae');
     return converted;
 }
+// DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
+// convertClaudeCommandToTraeSkill (dead for the live skills-install path,
+// which routes here via install-engine.cts's SKILLS_CONVERTER_REGISTRY; kept
+// for bin/install.js's own module-level export/test surface). Neither copy
+// re-exports the other — mirror any behavior change into both. Guarded by
+// the output-parity test in tests/runtime-converters.test.cjs (#2094).
 function convertClaudeCommandToTraeSkill(content, skillName) {
     const converted = convertClaudeToTraeMarkdown(content);
     const { frontmatter, body } = extractFrontmatterAndBody(converted);
@@ -1059,7 +1121,17 @@ function convertClaudeCommandToTraeSkill(content, skillName) {
     const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
     // #2876: quote so YAML flow indicators (`[BETA] …`) don't break Trae's
     // frontmatter parser.
-    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n${body}`;
+    let fm = `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n`;
+    // #2094: emit `stage:` so Trae's SOLO agent can auto-invoke GSD skills at
+    // the corresponding stage (docs.trae.ai/ide/agent). The field name/schema
+    // 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;
+    if (soloStage)
+        fm += `stage: ${soloStage}\n`;
+    fm += '---';
+    return `${fm}\n${body}`;
 }
 function convertSlashCommandsToCodebuddySkillMentions(content) {
     return content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
@@ -1520,7 +1592,12 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
     return `---\n${newFrontmatter}\n---${body}`;
 }
 // Kilo CLI — same conversion logic as OpenCode, different config paths.
-function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
+// DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
+// convertClaudeToKiloFrontmatter (used by bin/install.js's own legacy install
+// path). Neither copy re-exports the other — mirror any behavior change into
+// both. Guarded by the output-parity test in tests/runtime-converters.test.cjs
+// (#2093).
+function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
     // Replace tool name references in content (applies to all files)
     let convertedContent = content;
     convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
@@ -1666,6 +1743,14 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
     // For agents: add required Kilo agent fields
     if (isAgent) {
         newLines.push('mode: subagent');
+        // Embed model override from ~/.gsd/defaults.json so model_overrides is
+        // respected on Kilo (which uses static agent frontmatter, not inline
+        // Task() model parameters) — mirrors convertClaudeToOpencodeFrontmatter's
+        // 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(...buildKiloAgentPermissionBlock(agentTools));
     }
     // For commands: add tools object if we had allowed-tools or tools
@@ -1875,6 +1960,76 @@ function convertClaudeAgentToTraeAgent(content) {
     const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
     return `${cleanFrontmatter}\n${body}`;
 }
+/**
+ * Convert a Claude agent (.md) to a native Qwen Code subagent file
+ * (`.qwen/agents/gsd-*.md` / `<qwenhome>/agents/gsd-*.md`, ADR-1239 / #2092
+ * Phase B Upgrade 1). Qwen Code is a Claude-dialect host: its docs' "Claude
+ * Code Compatibility Fields" section confirms CC agent files parse under
+ * `.qwen/agents/` (https://qwenlm.github.io/qwen-code-docs/en/users/features/sub-agents),
+ * so — unlike Cursor/Trae/Copilot/Antigravity — tool names pass through
+ * UNCHANGED (no remapping table).
+ *
+ * Emits DETERMINISTIC frontmatter: `name:` + `description:` (mirrors
+ * convertClaudeAgentToCursorAgent), plus `tools:` as a YAML block list when the
+ * source declares one. Qwen's documented `tools:` schema is a YAML array
+ * (`tools:\n- tool1\n- tool2`), not Claude's single-line comma-separated string
+ * — passing the raw single-line string through unchanged would parse as one
+ * malformed tool name and be silently dropped ("Optional fields with invalid
+ * values are silently dropped at parse time" — same docs page). Reuses
+ * `parseFrontmatterTools` (already relied on by the Kimi agent path), which
+ * tolerates BOTH source formats Claude's own agents/*.md files use — the
+ * single-line comma list (most agents) and the YAML block list (e.g.
+ * agents/gsd-nyquist-auditor.md, agents/gsd-security-auditor.md) — so no tools
+ * are lost regardless of which the source agent uses.
+ *
+ * `color` IS preserved: Qwen's docs list `color` under "Claude Code
+ * Compatibility Fields" as a supported optional field, so it is passed
+ * through as a plain scalar (unlike the cursor/trae/augment/windsurf
+ * reduced-frontmatter converters, which drop it — those hosts have no such
+ * compatibility field). `model:` and `approvalMode:` are intentionally NOT
+ * emitted: both are optional per the docs and out of scope for #2092 (model:
+ * would couple to the model catalog and introduce nondeterminism;
+ * approvalMode is a deliberate follow-on).
+ *
+ * Body: preserved verbatim after the qwen branding rewrite (CLAUDE.md /
+ * Claude Code / .claude/ literal-substring values — descriptor-driven via
+ * runtime.hostBehaviors.brandingRewrites, mirrors the qwen case in
+ * _applyRuntimeRewrites). The anchored `~/.claude/` / `$HOME/.claude/` forms
+ * are already rewritten upstream by applyAgentPathRewrites (agentCtx Step 1 in
+ * stageAgentsForRuntimeWithConverter) before this converter runs, so only the
+ * bare/non-anchored forms are handled here — mirrors how
+ * convertClaudeToTraeMarkdown orders its bare-form rewrites after the slash
+ * forms to avoid double-rewriting the same substring.
+ */
+function convertClaudeAgentToQwenAgent(content) {
+    const _b = _hostBehaviors('qwen').brandingRewrites || {};
+    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/']);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const tools = parseFrontmatterTools(frontmatter);
+    const color = extractFrontmatterField(frontmatter, 'color');
+    let fm = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n`;
+    if (tools.length > 0) {
+        fm += 'tools:\n';
+        for (const tool of tools) {
+            fm += `  - ${yamlIdentifier(tool)}\n`;
+        }
+    }
+    if (color) {
+        fm += `color: ${yamlIdentifier(color)}\n`;
+    }
+    fm += '---';
+    return `${fm}\n${body}`;
+}
 function convertClaudeAgentToCodebuddyAgent(content) {
     const converted = convertClaudeToCodebuddyMarkdown(content);
     const { frontmatter, body } = extractFrontmatterAndBody(converted);
@@ -1989,8 +2144,8 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     // Without this, path.join on Windows produces a backslash prefix that
     // leaks into markdown content and breaks cross-platform substring checks.
     // See DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT in CONTEXT.md.
-    const posixTarget = String(resolvedTarget).replace(/\\/g, '/');
-    const posixHome = homeDir ? String(homeDir).replace(/\\/g, '/') : homeDir;
+    const posixTarget = (0, shell_command_projection_cjs_1.posixNormalize)(String(resolvedTarget));
+    const posixHome = homeDir ? (0, shell_command_projection_cjs_1.posixNormalize)(String(homeDir)) : homeDir;
     if (isGlobal && posixTarget.startsWith(posixHome) && !isOpencode) {
         return '$HOME' + posixTarget.slice(posixHome.length) + '/';
     }
@@ -2087,19 +2242,24 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = processAttribution(content, attribution);
             break;
         }
-        case 'augment':
+        case 'augment': {
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
             content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
             content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
             content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
-            content = content.replace(/~\/\.augment\//g, pathPrefix);
-            content = content.replace(/\$HOME\/\.augment\//g, pathPrefix);
-            content = content.replace(/~\/\.augment(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/\$HOME\/\.augment(?![\w-])/g, normalizedPathPrefix);
+            // #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);
+            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);
+            content = content.replace(new RegExp('\\$HOME/' + _dd + '(?![\\w-])', 'g'), normalizedPathPrefix);
             content = processAttribution(content, attribution);
             break;
+        }
         case 'trae':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
@@ -2107,7 +2267,10 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
             content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
             content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
-            content = content.replace(/~\/\.trae\//g, pathPrefix);
+            // #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 = processAttribution(content, attribution);
             break;
         case 'codebuddy':
@@ -2135,9 +2298,20 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
             content = processAttribution(content, attribution);
             break;
-        case 'qwen':
-            content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
-            content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
+        // Descriptor-driven brand literals (ADR-1239 / #2092): the qwen/hermes
+        // 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': {
+            // 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']);
+                content = content.replace(/\bClaude Code\b/g, _b['Claude Code']);
+            }
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/~\/\.qwen\//g, pathPrefix);
@@ -2146,14 +2320,22 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
             content = content.replace(/~\/\.qwen(?![\w-])/g, normalizedPathPrefix);
             content = content.replace(/\$HOME\/\.qwen(?![\w-])/g, normalizedPathPrefix);
-            content = content.replace(/\.claude\//g, '.qwen/');
+            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':
-            content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
-            content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
+        }
+        case 'hermes': {
+            // Guarded (post-review #2092): see qwen case above — same degrade-closed
+            // rationale.
+            const _b = _hostBehaviors(runtime).brandingRewrites;
+            if (_b) {
+                content = content.replace(/CLAUDE\.md/g, _b['CLAUDE.md']);
+                content = content.replace(/\bClaude Code\b/g, _b['Claude Code']);
+            }
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
             content = content.replace(/~\/\.hermes\//g, pathPrefix);
@@ -2162,11 +2344,14 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             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(/\.claude\//g, '.hermes/');
+            if (_b) {
+                content = content.replace(/\.claude\//g, _b['.claude/']);
+            }
             content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
             content = content.replace(/\.\/\.hermes\//g, `./${dirName}/`);
             content = processAttribution(content, attribution);
             break;
+        }
         case 'kimi':
             content = content.replace(/~\/\.claude\//g, pathPrefix);
             content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
@@ -2241,8 +2426,11 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
                 continue;
             let content = node_fs_1.default.readFileSync(node_path_1.default.join(stagedDir, entry.name), 'utf8');
             content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal, attribution);
-            if (runtime === 'augment') {
-                content = convertClaudeToAugmentMarkdown(content);
+            // #2097 (ADR-1239): descriptor-driven — commandBodyConverter name comes
+            // from runtime.hostBehaviors instead of a hardcoded runtime-name branch.
+            const _cmdConv = _hostBehaviors(runtime).commandBodyConverter;
+            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);
         }
@@ -2274,8 +2462,8 @@ 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))
         return;
-    const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
-    const homeDir = homedir().replace(/\\/g, '/');
+    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';
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
@@ -2303,8 +2491,8 @@ 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))
         return stagedDir;
-    const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
-    const homeDir = homedir().replace(/\\/g, '/');
+    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';
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
@@ -2312,25 +2500,21 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
     return applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix, isGlobal, attribution);
 }
-/**
- * Runtimes that use the hyphen-namespace form `/gsd-<cmd>` in agent bodies.
- * claude/qwen/hermes use hyphen-name:`...` frontmatter; cursor/windsurf/etc
- * self-convert. Mirrors the `HYPHEN_NAME_AGENT_RUNTIMES` set in bin/install.js.
- *
- * @private — export normalizeAgentBodyForRuntime for callers.
- */
-const HYPHEN_NAME_AGENT_RUNTIMES = new Set(['claude', 'qwen', 'hermes']);
 /**
  * Normalize `/gsd:<cmd>` colon refs in the agent body to `/gsd-<cmd>` for
- * hyphen-`name:` runtimes (claude / qwen / hermes). No-op for all other
- * runtimes. Mirrors the per-file call in bin/install.js line 9400.
+ * runtimes that declare `runtime.hostBehaviors.hyphenNameAgentBody` on their
+ * descriptor (claude / qwen / hermes use hyphen-`name:` frontmatter;
+ * cursor/windsurf/etc self-convert and don't declare the flag). Descriptor-
+ * driven (ADR-1239 / #2092) — folded from the hardcoded
+ * `HYPHEN_NAME_AGENT_RUNTIMES` allow-list set. Mirrors the per-file call in
+ * bin/install.js line 9370 / `shouldNormalizeHyphenNamespaceInAgentBody`.
  *
  * @param content   raw agent file content (post-converter)
  * @param runtime   canonical runtime ID
  * @param cmdNames  gsd command names from readGsdCommandNames()
  */
 function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
-    if (!HYPHEN_NAME_AGENT_RUNTIMES.has(runtime))
+    if (_hostBehaviors(runtime).hyphenNameAgentBody !== true)
         return content;
     return transformContentToHyphen(content, cmdNames);
 }
@@ -2342,9 +2526,13 @@ function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
  *   ~/\.claude\b → normalizedPathPrefix
  *   $HOME/\.claude\b → normalizedPathPrefix
  *
- * Skipped for copilot and antigravity (which do NOT do path rewrites in the
- * inline loop). NO stamp (_stampNonClaudeRuntimeDefaults) — agents are NOT
- * stamped in the inline loop.
+ * Skipped for any runtime that declares `hostBehaviors.noPathRewrite`
+ * (descriptor-driven, ADR-1239 / #2096 — folds the prior hardcoded
+ * `runtime === 'antigravity'` literal; Antigravity does NOT do path rewrites
+ * in the inline loop / #2103 — folds the prior hardcoded
+ * `runtime === 'copilot'` literal onto the same descriptor field, since
+ * copilot also skips these rewrites). NO stamp
+ * (_stampNonClaudeRuntimeDefaults) — agents are NOT stamped in the inline loop.
  *
  * ADR-1235 §1: pre-converter cross-cutting for descriptor-driven agent pipeline.
  * Exported as `applyAgentPathRewrites` for testing and for injection into
@@ -2353,10 +2541,10 @@ function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
  * @param content     raw agent file content
  * @param runtime     canonical runtime ID
  * @param pathPrefix  trailing-slash path prefix (e.g. '$HOME/.cursor/')
- * @returns content with path-prefix rewrites applied (or unchanged for copilot/antigravity)
+ * @returns content with path-prefix rewrites applied (or unchanged for noPathRewrite runtimes, e.g. copilot)
  */
 function applyAgentPathRewrites(content, runtime, pathPrefix) {
-    if (runtime === 'copilot' || runtime === 'antigravity')
+    if (_hostBehaviors(runtime).noPathRewrite === true)
         return content;
     const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
@@ -2392,6 +2580,11 @@ function processAttribution(content, attribution) {
 }
 module.exports = {
     processAttribution,
+    // #2103: public accessor for hostBehaviors.agentFileExtension, exported so
+    // surface.cts's _syncGsdDir can derive the .agent.md rename from the SAME
+    // descriptor read as install-engine.cts (folds a duplicated hardcoded
+    // `runtime === 'copilot'` literal).
+    agentFileExtensionFor,
     yamlIdentifier,
     yamlQuote,
     toSingleLine,
@@ -2451,6 +2644,11 @@ module.exports = {
     convertClaudeAgentToCodebuddyAgent,
     convertClaudeAgentToClineAgent,
     convertClaudeAgentToCodexAgent,
+    // 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,
     // #1511 ADR-1508 Phase 2: rewrite engine deep seam
     // Low-level walkers (pathPrefix + attribution pre-resolved by caller):
     applyRuntimeContentRewritesInPlace,

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

@@ -67,9 +67,10 @@ function createRuntimeArtifactInstallPlan(args) {
     // to kind.stage() for agents kind entries with a converter (convertedAgentsKind).
     // NO _stampNonClaudeRuntimeDefaults — agents are NOT stamped in the inline loop.
     const os = _require('node:os');
+    const { posixNormalize } = _require('./shell-command-projection.cjs');
     const homedirFn = homedir ?? (() => os.homedir());
-    const resolvedTarget = path.resolve(layout.configDir).replace(/\\/g, '/');
-    const homeDir = homedirFn().replace(/\\/g, '/');
+    const resolvedTarget = posixNormalize(path.resolve(layout.configDir));
+    const homeDir = posixNormalize(homedirFn());
     const isGlobal = scope === 'global';
     const isOpencode = layout.runtime === 'opencode';
     const isWindowsHost = (platform ?? process.platform) === 'win32';

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

@@ -23,6 +23,7 @@ const { stageSkillsForProfile, stageAgentsForProfile, stageAgentsForRuntimeWithC
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const conversionExports = runtimeArtifactConversion;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 // ---------------------------------------------------------------------------
@@ -130,19 +131,27 @@ function agentsKind(destSubpath, prefix, configDir) {
  * Agent filenames are preserved verbatim (the prefix is already embedded in the
  * agent stem — e.g. `gsd-planner.md`).
  *
- * #1173 SCOPE — plumbing only (declarations deferred): this provides the
- * converter dispatch + `isGlobal` scope threading for the descriptor's `agents`
- * kind, but NO runtime currently declares a converted `agents` kind in its
- * `capability.json`. The descriptor declarations for the 8 non-Claude runtimes
- * (copilot/antigravity/cursor/windsurf/augment/trae/codebuddy/cline) are
- * DEFERRED to a follow-up that first ships the ADR-1235 §0 byte-for-byte parity
- * harness, because the second `layout.kinds` consumer — `applySurface` /
- * `/gsd:surface` / `--materialize` (`src/surface.cts`) — does not yet mirror the
- * legacy agent pipeline (Copilot's `.agent.md` filename rename, the cross-cutting
- * path-prefix rewrite + attribution, stale-file cleanup, config-reading steps),
- * so declaring the kind now would regress the surface path. Until then the legacy
- * `bin/install.js` agent loop remains authoritative for the real install, and
- * this `convertedAgentsKind` is exercised only by synthetic-descriptor seam tests.
+ * #1173 SCOPE — plumbing only (real install still elsewhere): this provides
+ * the converter dispatch + `isGlobal` scope threading for the descriptor's
+ * `agents` kind. As of #2092, 8 non-Claude runtimes DO declare a converted
+ * `agents` kind in their `capability.json` — qwen (`convertClaudeAgentToQwenAgent`)
+ * plus the 7 that already declared one before it (antigravity, augment,
+ * codebuddy, copilot, cursor, trae, windsurf) — so the descriptor-level
+ * declaration is no longer deferred. What IS still deferred is wiring
+ * `resolveRuntimeArtifactLayout`'s `agents` kind into the REAL install:
+ * `bin/install.js`'s agent-staging loop does not consume this module's
+ * `convertedAgentsKind` resolution at all — it dispatches the very same
+ * converter functions directly via `_hostBehaviors(runtime)` checks
+ * (`frontmatterDialect`, `brandingRewrites`, `isCopilot`/`isAntigravity`/…),
+ * duplicating the mapping declared here. That duplication is deliberate until
+ * the second `layout.kinds` consumer — `applySurface` / `/gsd:surface` /
+ * `--materialize` (`src/surface.cts`) — mirrors the legacy agent pipeline
+ * (Copilot's `.agent.md` filename rename, the cross-cutting path-prefix
+ * rewrite + attribution, stale-file cleanup, config-reading steps); declaring
+ * `bin/install.js` itself against this resolver before then would risk
+ * regressing the surface path. Until that follow-up lands, `bin/install.js`
+ * remains authoritative for the real install, and this `convertedAgentsKind`
+ * is exercised only by `/gsd:surface` and synthetic-descriptor seam tests.
  *
  * Mirrors the `convertedCommandsKind` pattern (#785).
  *
@@ -184,7 +193,7 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
                         continue;
                     const agentPath = node_path_1.default.join(stagedAgents, entry.name);
                     subagents.push({
-                        path: node_path_1.default.join('agents', entry.name).replace(/\\/g, '/'),
+                        path: (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.join('agents', entry.name)),
                         content: node_fs_1.default.readFileSync(agentPath, 'utf8'),
                     });
                 }
@@ -224,6 +233,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
         kind: 'skills',
         destSubpath,
         prefix,
+        converter: converterName,
         stage: (resolved) => {
             const realConverter = conversionExports[converterName];
             // Compute cmdNames once per stage call for performance (#3583).

package/gsd-core/bin/lib/runtime-config-adapter-registry.cjs

@@ -21,17 +21,30 @@
  *     false for codex / copilot / kilo / cursor / windsurf / trae / cline / kimi (legacy exclusion list).
  *     true for all other runtimes.
  * - `finishPermissionWriter` names the finishInstall-phase dedicated config writer:
- *     'opencode' → writes BOTH shared settings AND its own permissions file.
- *     'kilo'     → writes only its own permissions file.
- *     null       → no dedicated permission writer.
+ *     'opencode'    → writes BOTH shared settings AND its own permissions file.
+ *     'kilo'        → writes only its own permissions file.
+ *     'antigravity' → writes BOTH shared settings.json permissions.allow AND a
+ *                      standalone mcp_config.json MCP companion profile (#2096
+ *                      Phase B Upgrades 1+2).
+ *     null          → no dedicated permission writer.
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { runtimes } = require('./capability-registry.cjs');
 /** Valid sandboxTier enum values — mirrors the gen-capability-registry validator vocabulary. */
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
-/** The complete set of 16 supported runtimes for config-adapter dispatch. */
+/**
+ * The complete set of 16 supported runtimes for config-adapter dispatch.
+ *
+ * Excludes runtimes whose installSurface is 'none' (#2103 — e.g. VS Code): a
+ * 'none' installSurface means the runtime has NO CLI install surface at all
+ * (Marketplace/VSIX-distributed, never dispatched through
+ * install()/finishInstall()), so it is not a "config-adapter runtime" by
+ * definition. This keeps this set in lockstep with bin/install.js's
+ * `allRuntimes` (see tests/issue-57-runtime-install-no-drift.test.cjs) without
+ * needing a separate hand-kept exclusion list.
+ */
 const ALLOWED_CONFIG_RUNTIMES = new Set(Object.entries(runtimes)
-    .filter(([, cap]) => cap && cap.runtime && typeof cap.runtime['installSurface'] === 'string')
+    .filter(([, cap]) => cap && cap.runtime && typeof cap.runtime['installSurface'] === 'string' && cap.runtime['installSurface'] !== 'none')
     .map(([id]) => id));
 /** All valid installSurface values. */
 const INSTALL_SURFACES = Object.freeze([
@@ -41,6 +54,7 @@ const INSTALL_SURFACES = Object.freeze([
     'cline-rules',
     'cursor-hooks-json',
     'profile-marker-only',
+    'none',
 ]);
 /**
  * Resolve the config adapter intent for a given runtime.