@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/gsd-core/bin/lib/install-engine.cjs

@@ -26,6 +26,7 @@ const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
+const installProfiles = require("./install-profiles.cjs");
 const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
@@ -51,6 +52,25 @@ const { getDirName } = runtimeNamePolicy;
  */
 const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
 // ---------------------------------------------------------------------------
+// Host-behavior helpers
+// ---------------------------------------------------------------------------
+/**
+ * Host-specific install behaviors declared on the runtime descriptor
+ * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors).
+ * Mirrors bin/install.js's `_hostBehaviors` (ADR-1239 / #2086/#2087). Returns
+ * {} for runtimes that declare none or if the registry fails to load, so
+ * every behavior branch degrades to the generic path by default.
+ */
+function _hostBehaviors(runtime) {
+    try {
+        const reg = require('./capability-registry.cjs');
+        return (reg && reg.runtimes && reg.runtimes[runtime] && reg.runtimes[runtime].runtime && reg.runtimes[runtime].runtime.hostBehaviors) || {};
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------------------
 // Conversion helpers
 // ---------------------------------------------------------------------------
 /**
@@ -82,6 +102,17 @@ function convertClaudeCommandToOpencodeSkill(content, skillName) {
 function convertClaudeCommandToKiloSkill(content, skillName) {
     return runtimeArtifactConversion.convertClaudeCommandToKiloSkill(content, skillName);
 }
+/**
+ * Converter-name registry for the OpenCode-family combined skills installer
+ * (ADR-1239 / #2093). Maps the `converter` string declared on each runtime's
+ * artifactLayout skills-kind descriptor (capabilities/<runtime>/capability.json)
+ * to the actual conversion function, so `installOpencodeFamilySkills` dispatches
+ * off the descriptor instead of a `frontmatterDialect === 'kilo'` runtime check.
+ */
+const SKILLS_CONVERTER_REGISTRY = {
+    convertClaudeCommandToOpencodeSkill,
+    convertClaudeCommandToKiloSkill,
+};
 // ---------------------------------------------------------------------------
 // User-artifact preservation helpers
 // ---------------------------------------------------------------------------
@@ -231,14 +262,20 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
     if (configDir === undefined) {
         throw new Error('_copyStaged: configDir (install root) is required to confine writes — refusing to write');
     }
+    // The install root is normally configDir, but a kind may declare an alternate
+    // `home` (ADR-1239 upgrade 3 / #2088, e.g. Codex skills -> $HOME/.agents) — in
+    // that case this defense-in-depth check must confine against the resolved
+    // alternate root instead, matching the upstream gate's own root selection in
+    // createRuntimeArtifactInstallPlan.
+    const installRoot = (kind && typeof kind.home === 'string' && kind.home !== '') ? kind.home : configDir;
     // Strict-subpath + NUL containment via the canonical gate (shared with the
     // layout-driven install plan); throws if destDir escapes the install root.
-    // destDir here is an absolute path; path.resolve(configDir, absoluteDest) returns it unchanged, so the gate's strict-subpath check still correctly confines it to configDir.
-    const resolvedDest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, destDir);
-    // Symlink-escape guard: reject if any path component between configDir and
-    // destDir is a symlink that would redirect writes outside configDir.
-    if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), resolvedDest)) {
-        throw new Error(`_copyStaged: destDir "${destDir}" contains a symlink escaping the install root "${configDir}" — refusing to write`);
+    // destDir here is an absolute path; path.resolve(installRoot, absoluteDest) returns it unchanged, so the gate's strict-subpath check still correctly confines it to installRoot.
+    const resolvedDest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, destDir);
+    // Symlink-escape guard: reject if any path component between the install root and
+    // destDir is a symlink that would redirect writes outside the install root.
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), resolvedDest)) {
+        throw new Error(`_copyStaged: destDir "${destDir}" contains a symlink escaping the install root "${installRoot}" — refusing to write`);
     }
     // Use the validated absolute path for the actual writes below.
     destDir = resolvedDest;
@@ -276,9 +313,13 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
         let destName;
         if (kind.kind === 'agents') {
             // Agent files already carry the gsd- prefix in the source dir.
-            // #1575: copilot agents get .agent.md suffix (mirrors inline loop line ~9118).
-            destName = runtime === 'copilot'
-                ? entry.name.replace(/\.md$/, '.agent.md')
+            // #2099: descriptor-driven via hostBehaviors.agentFileExtension (was
+            // hardcoded `runtime === 'copilot'`). copilot declares '.agent.md';
+            // every other runtime's descriptor leaves this unset, so destName falls
+            // back to entry.name unchanged (byte-parity, #1575 origin comment).
+            const _agentExt = runtime ? _hostBehaviors(runtime).agentFileExtension : undefined;
+            destName = _agentExt
+                ? entry.name.replace(/\.md$/, _agentExt)
                 : entry.name;
         }
         else if (namespacedByDir) {
@@ -414,7 +455,7 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
     // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
     // created skills/gsd-dev-preferences/ skill dir.
     let savedLegacyArtifacts = null;
-    if (runtime === 'claude' || runtime === 'qwen' || runtime === 'hermes') {
+    if (_hostBehaviors(runtime).legacyCommandsGsdInstallMigration) {
         if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
             savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
             node_fs_1.default.rmSync(legacyCommandsGsd, { recursive: true });
@@ -471,7 +512,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
     // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
     // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
     // (which would redirect to skills/) conflicts with the test contract for local installs.
-    const isLegacyCommandsGsd = runtime === 'qwen' || runtime === 'hermes' || (runtime === 'claude' && scope === 'global');
+    const _lu = _hostBehaviors(runtime).legacyCommandsGsdUninstall;
+    const isLegacyCommandsGsd = _lu === true || (_lu === 'global' && scope === 'global');
     if (isLegacyCommandsGsd) {
         const legacyCommandsGsd = node_path_1.default.join(configDir, 'commands', 'gsd');
         if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
@@ -519,6 +561,15 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  * @param resolveAttribution  injection: (runtime) => attribution string | undefined
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined) {
+    // Combined-family runtimes (OpenCode/Kilo, ADR-1239 / #2087): route through
+    // the dedicated combined commands+skills+plugin orchestrator instead of the
+    // generic layout-driven loop below, mirroring the bespoke install path that
+    // previously lived inline in bin/install.js.
+    const behaviors = _hostBehaviors(runtime);
+    if (behaviors.combinedFamilyInstall) {
+        installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors);
+        return;
+    }
     // Legacy cleanup before layout-driven writes
     _runLegacyInstallMigrations(runtime, configDir, scope);
     const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope);
@@ -543,10 +594,16 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                 throw new Error(`Install plan returned unknown artifact kind: ${item.kind}`);
             const dest = item.destDir;
             // Symlink-escape guard: reject before mkdir if dest (or any component
-            // between configDir and dest) is a symlink pointing outside configDir.
-            // mkdirSync follows symlinks, so this must run BEFORE the mkdir call.
-            if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), dest)) {
-                throw new Error(`installRuntimeArtifacts: destDir "${dest}" contains a symlink escaping the install root "${configDir}" — refusing to create`);
+            // between the install root and dest) is a symlink pointing outside that
+            // root. mkdirSync follows symlinks, so this must run BEFORE the mkdir
+            // call. The install root is normally configDir, but a kind may declare
+            // an alternate `home` (ADR-1239 upgrade 3 / #2088, e.g. Codex skills ->
+            // $HOME/.agents) — in that case the guard must check against the
+            // resolved alternate root instead, matching assertDestWithinConfigHome's
+            // own root selection in createRuntimeArtifactInstallPlan.
+            const installRoot = (kind && typeof kind.home === 'string' && kind.home !== '') ? kind.home : configDir;
+            if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), dest)) {
+                throw new Error(`installRuntimeArtifacts: destDir "${dest}" contains a symlink escaping the install root "${installRoot}" — refusing to create`);
             }
             node_fs_1.default.mkdirSync(dest, { recursive: true });
             if (kind.kind === 'skills' && node_fs_1.default.existsSync(dest)) {
@@ -610,6 +667,18 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
         _removeHermesBareStemDirs(nestedGsdDirForCleanup);
     }
+    // Generic-branch nativePlugin staging (ADR-1239 / #2102 Stage 1): runtimes
+    // outside the OpenCode/Kilo combined-family install (e.g. pi, whose
+    // artifactLayout is empty and which never sets combinedFamilyInstall) still
+    // need their declared hostBehaviors.nativePlugin file copied into configDir.
+    // findInstallSourceRoot resolves the repo/package root independent of
+    // configDir contents (marker check, then a walk-up from __dirname), so this
+    // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
+    if (behaviors.nativePlugin) {
+        const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
+        const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+        _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
+    }
 }
 // ---------------------------------------------------------------------------
 // installOpencodeFamilySkills
@@ -638,9 +707,16 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     const rawDir = rawCommandsDir;
     if (!rawDir || !node_fs_1.default.existsSync(rawDir))
         return 0;
-    const converter = runtime === 'kilo'
-        ? convertClaudeCommandToKiloSkill
-        : convertClaudeCommandToOpencodeSkill;
+    // #2093: descriptor-driven — dispatch off the skills-kind entry's `converter`
+    // string (capabilities/<runtime>/capability.json artifactLayout) via the
+    // SKILLS_CONVERTER_REGISTRY, instead of a `frontmatterDialect === 'kilo'`
+    // runtime check. Fail loud if the descriptor names an unregistered converter
+    // (mirrors the converter=null throw in runtime-artifact-layout.cts).
+    const converterName = skillsKindEntry.converter;
+    const converter = converterName ? SKILLS_CONVERTER_REGISTRY[converterName] : undefined;
+    if (!converter) {
+        throw new TypeError(`installOpencodeFamilySkills: unknown skills converter '${String(converterName)}' for runtime '${runtime}'`);
+    }
     const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
     // Symlink-escape guard: reject if any path component between targetDir and
     // dest is a symlink that would redirect writes outside the config root.
@@ -686,6 +762,136 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     return count;
 }
 // ---------------------------------------------------------------------------
+// installOpencodeFamilyCommands
+// ---------------------------------------------------------------------------
+/**
+ * Install the flattened commands surface for an OpenCode-family runtime
+ * (OpenCode/Kilo): commands/gsd/**\/*.md -> command/gsd-<...>.md, with
+ * per-runtime frontmatter conversion and path-prefix/attribution rewrites.
+ *
+ * Mirrors bin/install.js's copyFlattenedCommands VERBATIM (ADR-1239 /
+ * #2087), except attribution is resolved via the injected
+ * `resolveAttribution` callback instead of a module-level getCommitAttribution.
+ *
+ * @param runtime - 'opencode' or 'kilo'
+ * @param destDir - destination directory for flattened commands (recurses with the same destDir)
+ * @param srcDir - source directory to walk (commands/gsd/, recursing into subdirectories)
+ * @param pathPrefix - computed config-path prefix for body rewrites
+ * @param resolveAttribution - injection: (runtime) => attribution string | undefined
+ * @param prefix - filename prefix accumulator (defaults to 'gsd'; grows on recursion)
+ */
+function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, resolveAttribution = () => undefined, prefix = 'gsd') {
+    if (!node_fs_1.default.existsSync(srcDir))
+        return;
+    // Remove old gsd-*.md files before copying new ones
+    if (node_fs_1.default.existsSync(destDir)) {
+        for (const file of node_fs_1.default.readdirSync(destDir)) {
+            if (file.startsWith(`${prefix}-`) && file.endsWith('.md'))
+                node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
+        }
+    }
+    else {
+        node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    }
+    for (const entry of node_fs_1.default.readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = node_path_1.default.join(srcDir, entry.name);
+        if (entry.isDirectory()) {
+            installOpencodeFamilyCommands(runtime, destDir, srcPath, pathPrefix, resolveAttribution, `${prefix}-${entry.name}`);
+        }
+        else if (entry.name.endsWith('.md')) {
+            const baseName = entry.name.replace('.md', '');
+            const destName = `${prefix}-${baseName}.md`;
+            let content = node_fs_1.default.readFileSync(srcPath, 'utf8');
+            content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
+            content = processAttribution(content, resolveAttribution(runtime));
+            // #2093: this commands-kind entry's descriptor `converter` field is
+            // intentionally `null` (see capabilities/{kilo,opencode}/capability.json —
+            // the flattened-command writer above applies its own path/attribution
+            // rewrites and has no per-file converter slot to key on), so there is no
+            // descriptor string to dispatch through here. `frontmatterDialect` is the
+            // documented, intentional dispatch key for frontmatter-shape selection —
+            // it is itself descriptor-driven (not a `runtime === 'kilo'` check), so it
+            // already satisfies the fold-to-descriptor requirement. Only the SKILLS
+            // converter site above (installOpencodeFamilySkills) has a real
+            // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
+            content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
+                ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
+                : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, destName), content);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// _installNativePluginIfDeclared
+// ---------------------------------------------------------------------------
+/**
+ * Copy a runtime's declared native-extension/plugin file (hostBehaviors.nativePlugin)
+ * into its resolved config dir, when the runtime descriptor declares one.
+ *
+ * Extracted (ADR-1239 / #2102 Stage 1) from the body previously inlined in
+ * installOpencodeFamilyArtifacts so a runtime that is NOT part of the
+ * OpenCode/Kilo combined-family install (e.g. pi, whose artifactLayout is
+ * empty and which never sets combinedFamilyInstall) can still get its
+ * nativePlugin file staged via the generic installRuntimeArtifacts branch.
+ * Behavior for opencode/kilo is unchanged — same source resolution, same
+ * mkdir + copyFileSync call, same silent no-op when the source is missing.
+ *
+ * @param runtime  - canonical runtime id (only used for the assertDestWithinConfigHome guard)
+ * @param configDir - resolved runtime config directory
+ * @param behaviors - the runtime's hostBehaviors descriptor
+ * @param src       - repo/package root (two levels up from the commands/gsd source dir)
+ */
+function _installNativePluginIfDeclared(runtime, configDir, behaviors, src) {
+    const np = behaviors.nativePlugin;
+    if (np && np.source) {
+        const pluginSrc = node_path_1.default.join(src, np.source);
+        if (node_fs_1.default.existsSync(pluginSrc)) {
+            const destDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, np.dir);
+            node_fs_1.default.mkdirSync(destDir, { recursive: true });
+            node_fs_1.default.copyFileSync(pluginSrc, node_path_1.default.join(destDir, np.file));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// installOpencodeFamilyArtifacts
+// ---------------------------------------------------------------------------
+/**
+ * Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087,
+ * #2093). Stages the flattened commands surface + skills surface + (any
+ * runtime whose hostBehaviors declares `nativePlugin` — OpenCode and, since
+ * #2093, Kilo) native plugin adapter, mirroring the bespoke `else if (isOpencode ||
+ * isKilo)` block previously inlined in bin/install.js.
+ *
+ * @param runtime - 'opencode' or 'kilo'
+ * @param configDir - resolved runtime config directory
+ * @param scope - install scope ('global' | 'local')
+ * @param resolvedProfile - from resolveProfile() / resolveEffectiveProfile()
+ * @param resolveAttribution - injection: (runtime) => attribution string | undefined
+ * @param behaviors - the runtime's hostBehaviors descriptor (already resolved by the caller)
+ */
+function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}) {
+    const isGlobal = scope === 'global';
+    // findInstallSourceRoot resolves DIRECTLY to the commands/gsd source dir
+    // (via the .gsd-source marker or a walk-up from __dirname) — every other
+    // call site in runtime-artifact-layout.cts feeds its return value straight
+    // into stageSkillsForProfile/stageSkillsForRuntimeAsSkills. The repo/package
+    // root (needed below for the native plugin source) is two levels up.
+    const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
+    const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+    const rawCommandsDir = installProfiles.stageSkillsForProfile(commandsGsdDir, resolvedProfile);
+    const pathPrefix = runtimeArtifactConversion._computePathPrefix({
+        isGlobal,
+        isOpencode: behaviors.skipHomePrefixSubstitution === true,
+        isWindowsHost: process.platform === 'win32',
+        resolvedTarget: node_path_1.default.resolve(configDir).replace(/\\/g, '/'),
+        homeDir: node_os_1.default.homedir().replace(/\\/g, '/'),
+    });
+    const commandDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, 'command');
+    installOpencodeFamilyCommands(runtime, commandDir, rawCommandsDir, pathPrefix, resolveAttribution);
+    installOpencodeFamilySkills(runtime, configDir, rawCommandsDir, pathPrefix, resolveAttribution);
+    _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
+}
+// ---------------------------------------------------------------------------
 // uninstallRuntimeArtifacts
 // ---------------------------------------------------------------------------
 /**
@@ -740,6 +946,10 @@ module.exports = {
     installRuntimeArtifacts,
     uninstallRuntimeArtifacts,
     installOpencodeFamilySkills,
+    installOpencodeFamilyCommands,
+    installOpencodeFamilyArtifacts,
+    _installNativePluginIfDeclared,
+    _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,
     preserveUserArtifacts,

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -37,7 +37,14 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-config-reload.js',
     'hooks/gsd-context-monitor.js',
     'hooks/gsd-cursor-post-tool.js',
+    'hooks/gsd-cursor-pre-tool.js',
     'hooks/gsd-cursor-session-start.js',
+    'hooks/gsd-cursor-stop.js',
+    'hooks/gsd-cursor-subagent-start.js',
+    'hooks/gsd-cursor-subagent-stop.js',
+    // Windsurf/Cascade blocking hooks — registered by writeWindsurfHooksJson (#2100).
+    'hooks/gsd-windsurf-pre-write.js',
+    'hooks/gsd-windsurf-pre-command.js',
     'hooks/gsd-ensure-canonical-path.js',
     'hooks/gsd-graphify-update.sh',
     'hooks/gsd-phase-boundary.sh',

package/gsd-core/bin/lib/loop-resolver.cjs

@@ -401,6 +401,25 @@ function renderLoopHooks(resolved) {
  * Missing <capId> value → coreError + non-zero exit.
  * Unknown/inactive capId → `false` (not an error).
  */
+// #2009: a capability id surfaced inside the runnable `gsd capability remove <id>`
+// remediation must match the canonical kebab-case id shape (identical to
+// capability-consent.cts / capability-ledger.cts) before it is embedded — a raw
+// overlay directory name is attacker-controlled and can carry shell/markdown
+// metacharacters (backticks, ';', '|', '$()'). An id that fails this check is
+// withheld and no runnable command is rendered for it.
+const LOAD_FAIL_CAP_ID_RE = /^[a-z][a-z0-9-]*$/;
+// #2009: neutralize control chars, newlines, and backticks from a third-party
+// load-failure reason so a malicious manifest cannot break out of the warning
+// line or inject markdown / prompt content into the surfaced message.
+function sanitizeLoadFailReason(reason) {
+    const cleaned = String(reason)
+        // Strip C0 control chars, DEL, and backticks; collapse remaining whitespace.
+        .replace(/[\x00-\x1F\x7F`]/g, ' ')
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 300);
+    return cleaned || '(no reason given)';
+}
 function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (!point) {
         coreError('loop render-hooks requires a <point> argument. Valid points: ' + CANONICAL_POINTS.join(', '));
@@ -456,26 +475,54 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         coreError(msg);
         return;
     }
-    // ── ADR-1244 D2 fail-closed gate injection ────────────────────────────────────
-    // For every skipped overlay capability that declared a gate at this point,
-    // inject a synthetic BLOCKING gate into the resolved output so the loop HALTS
-    // rather than silently proceeding as if the gate had passed. step/contribution
-    // overlays that were skipped are left open (skip-open is correct for them).
+    // ── ADR-1244 D2: load-failed capability gates FAIL OPEN with a loud warning ────
+    // Decision (#2009): a capability that failed to LOAD must not block the loop.
+    // The prior behavior injected a BLOCKING synthetic gate (blocking:true,
+    // onError:'halt') at every point where the skipped cap declared a gate, so a
+    // single incompatible capability halted every ship:pre / verify:post
+    // project-wide for a load error unrelated to what the gate checked — with no
+    // remediation surfaced. We now fail OPEN: no gate is injected (the loop proceeds
+    // and `--active-cap <failed-cap>` correctly reports it inactive), and a loud
+    // warning is emitted instead — to STDERR (which the operator, or the agent
+    // running the command, actually sees regardless of how the host workflow
+    // consumes stdout) AND in the envelope's `warnings` channel for structured
+    // consumers. The warning names the load reason and the exact
+    // `gsd capability remove <id>` remediation so the operator can clear the broken
+    // capability. blockedGates is still recorded by the loader; only the consequence
+    // changes from block to warn. step/contribution overlays were already skip-open.
+    //
+    // The gate injection was dropped rather than made non-blocking because no host
+    // workflow generically surfaces an arbitrary gate's message at ship:pre /
+    // verify:post (consumers dispatch on specific capIds / ref.skills), and the
+    // generic gate consumers expect an object-shaped `check`, not a prose string —
+    // so an injected advisory gate would be silently dropped or mis-dispatched. A
+    // stderr warning is the channel that is actually surfaced. (See #2009 review.)
     const overlayMeta = registry['_overlay'];
+    const loadFailWarnings = [];
     if (overlayMeta && Array.isArray(overlayMeta.blockedGates)) {
         for (const blocked of overlayMeta.blockedGates) {
-            if (blocked.point === point) {
-                const syntheticGate = {
-                    capId: blocked.capId,
-                    kind: 'gate',
-                    blocking: true,
-                    onError: 'halt',
-                    check: `capability "${blocked.capId}" was skipped at load (${blocked.reason}); its gate at ${point} cannot be evaluated — failing closed`,
-                };
-                resolved.activeHooks.push(syntheticGate);
-            }
+            if (blocked.point !== point)
+                continue;
+            // Security (#2009 review): capId/reason come from a third-party manifest or
+            // directory name. Validate capId before embedding it in the runnable
+            // remediation command; withhold it (no runnable command) if it is not a
+            // canonical id. Strip control chars/backticks from reason.
+            const idValid = LOAD_FAIL_CAP_ID_RE.test(String(blocked.capId));
+            const capLabel = idValid
+                ? `"${blocked.capId}"`
+                : 'with an invalid id (withheld) under .gsd/capabilities/';
+            const remediation = idValid
+                ? `Run \`gsd capability remove ${blocked.capId}\` to remove it, or fix the load error.`
+                : 'Remove the offending capability directory under .gsd/capabilities/, or fix the load error.';
+            loadFailWarnings.push(`capability ${capLabel} failed to load (${sanitizeLoadFailReason(blocked.reason)}); ` +
+                `its gate at ${point} is SKIPPED and NOT enforced (failing open). ${remediation}`);
         }
     }
+    // Emit loudly to stderr in EVERY output mode (including --active-cap), so a
+    // skipped gate is never silently invisible to the operator/agent.
+    for (const w of loadFailWarnings) {
+        process.stderr.write(`gsd: warning — ${w}\n`);
+    }
     // --active-cap mode: print exactly 'true' or 'false' with no envelope
     if (activeCapId !== undefined) {
         const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
@@ -488,8 +535,12 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         activeHooks: resolved.activeHooks,
         rendered,
     };
-    if (state.warnings && state.warnings.length > 0) {
-        envelope.warnings = state.warnings;
+    // Surface capability-state warnings and the #2009 load-failure fail-open
+    // warnings together in the structured `warnings` channel (in addition to the
+    // stderr emission above, which is the channel host workflows actually see).
+    const combinedWarnings = [...(state.warnings || []), ...loadFailWarnings];
+    if (combinedWarnings.length > 0) {
+        envelope.warnings = combinedWarnings;
     }
     coreOutput(envelope, raw);
 }

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -17,6 +17,7 @@ exports.collectSections = collectSections;
 exports.collectSection = collectSection;
 exports.iterateBullets = iterateBullets;
 exports.extractTaggedBlocks = extractTaggedBlocks;
+exports.stripTaggedBlocks = stripTaggedBlocks;
 exports.replaceSection = replaceSection;
 // ─── stripFencedCode ──────────────────────────────────────────────────────────
 /**
@@ -407,25 +408,26 @@ function iterateBullets(sectionText) {
  * fenced code blocks itself. If a `<tagName>` block appears inside a fenced code
  * block and should be excluded, the caller should apply `stripFencedCode` first.
  *
- * **Nested tags are NOT supported.** The underlying regex uses a non-greedy
- * `[\s\S]*?` match, which means it closes at the FIRST `</tagName>` encountered.
- * Given `<x><x>inner</x></x>`, `extractTaggedBlocks(content, 'x')` returns
- * `['<x>inner']` — the inner `<x>` is captured as literal text, and the second
- * `</x>` is left unmatched (or matched as a second block with empty inner text
- * if another `<x>` follows). Callers that need to handle nested tags must
- * pre-process the input or use a proper XML/HTML parser.
+ * **Nested tags are NOT supported.** The body scan terminates at the NEXT
+ * opening of the same tag (the ReDoS-safe boundary, #2128). Given
+ * `<x><x>inner</x></x>`, `extractTaggedBlocks(content, 'x')` returns `['inner']`
+ * — the well-formed inner block; the unterminated outer `<x>` is skipped.
+ * Callers that need true nesting must use a proper XML/HTML parser.
+ *
+ * `allowAttributes` (default `false`): when `true`, the opening tag may carry
+ * bounded attributes (`<tag foo="x">`) — needed for `<task type="…">` blocks.
+ * Leave `false` for tags that must match exactly (e.g. `<decisions>`), and never
+ * enable it for a tag where an attributed form is semantically distinct.
  *
  * Generalises `decisions.cts`'s bespoke `matchAll(/<decisions>([\s\S]*?)<\/decisions>/g)`
  * so tier T1 can drop its own copy (tracked duplication until T1 lands).
  */
-function extractTaggedBlocks(content, tagName) {
+function extractTaggedBlocks(content, tagName, allowAttributes = false) {
     if (typeof content !== 'string' || content.length === 0)
         return [];
     if (typeof tagName !== 'string' || tagName.length === 0)
         return [];
-    // Escape the tag name for safe interpolation into a RegExp.
-    const escapedTag = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`<${escapedTag}>([\\s\\S]*?)</${escapedTag}>`, 'g');
+    const pattern = taggedBlockPattern(tagName, 'g', allowAttributes);
     const results = [];
     let match;
     while ((match = pattern.exec(content)) !== null) {
@@ -433,6 +435,43 @@ function extractTaggedBlocks(content, tagName) {
     }
     return results;
 }
+/**
+ * Build the single, ReDoS-safe `<tag>…</tag>` block regex shared by
+ * `extractTaggedBlocks` (extract bodies) and `stripTaggedBlocks` (remove blocks).
+ *
+ * Safety: the body terminates at the NEXT opening of this tag (stop-at-next-open)
+ * instead of lazily rescanning the whole remaining document for a `</tag>` that
+ * may never appear — so a document full of unclosed `<tag>` openings scans
+ * LINEARLY, not quadratically (#2128). Group 1 is the block body.
+ *
+ * `allowAttributes`: when `true`, the opener accepts bounded attributes
+ * (`<tag foo="x">`) and the body boundary is `<tag` followed by a space or `>`.
+ * When `false`, the opener is the EXACT `<tag>` and the boundary is exact `<tag>`,
+ * so an attributed `<tag foo>` is neither an opener nor a boundary — it is body
+ * content. That exact form is load-bearing for `<details>` stripping: `<details
+ * open>` marks the ACTIVE milestone and must be preserved, not stripped (#557).
+ */
+function taggedBlockPattern(tagName, flags, allowAttributes) {
+    const esc = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const open = allowAttributes ? `<${esc}(?:\\s[^>]{0,1000})?>` : `<${esc}>`;
+    const boundary = allowAttributes ? `<${esc}[\\s>]` : `<${esc}>`;
+    return new RegExp(`${open}((?:(?!${boundary})[\\s\\S])*?)</${esc}>`, flags);
+}
+/**
+ * Remove every `<tagName>…</tagName>` block (opening tag, body, and closing tag)
+ * from `content`. The ReDoS-safe counterpart to `extractTaggedBlocks` — same
+ * hardened pattern, `.replace(…, '')` instead of body extraction. `allowAttributes`
+ * defaults to `false` so `<details open>` (active milestone) is preserved (#557);
+ * case-insensitive by default (matching the `<details>` strip call sites), pass
+ * `caseSensitive` to force exact-case matching.
+ */
+function stripTaggedBlocks(content, tagName, allowAttributes = false, caseSensitive = false) {
+    if (typeof content !== 'string' || content.length === 0)
+        return '';
+    if (typeof tagName !== 'string' || tagName.length === 0)
+        return content;
+    return content.replace(taggedBlockPattern(tagName, caseSensitive ? 'g' : 'gi', allowAttributes), '');
+}
 // ─── replaceSection ───────────────────────────────────────────────────────────
 /**
  * Splice `newBody` in place of a section's body and return the resulting

package/gsd-core/bin/lib/mcp-server.cjs

@@ -5,8 +5,16 @@
  * so any MCP-consuming host (Claude/Codex/OpenCode/VS Code/Gemini/Cursor/Cline/
  * Hermes) can drive GSD with NO bespoke plugin:
  *
- *   - point 1 (command): tool `gsd_invoke_command` → the command-routing hub
- *     (`createHub`/`dispatch`, src/command-routing-hub.cts).
+ *   - point 1 (command): tool `gsd_invoke_command` → `dispatchGsdCommand`
+ *     (src/shell-command-projection.cts), a bounded subprocess-shim to
+ *     gsd-tools.cjs. #2102 Stage 2: `commandRoutingHub.createHub()` called
+ *     with no args here always hit `if(!_cjsRegistry) return
+ *     makeUnknownCommand()` — every dispatch was UnknownCommand. No
+ *     fully-populated hub factory exists anywhere in gsd-core (every
+ *     createHub() caller builds a single-family hub for its own narrow
+ *     purpose), so the fix routes through the SAME shared dispatch helper
+ *     the pi extension uses (pi/gsd.cjs), mirroring the SUBPROCESS-REUSE
+ *     precedent already established for the OpenCode/Kilo hook bridge.
  *   - point 5 (state IO): tools `gsd_read_state` / `gsd_write_state` → the
  *     Phase 3 `stateIO` seam (src/state-io.cts, filesystem default).
  *
@@ -24,9 +32,10 @@ exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
 exports.handleMessage = handleMessage;
 exports.runServer = runServer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const commandRoutingHub = require("./command-routing-hub.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateIo = require("./state-io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const shellCommandProjection = require("./shell-command-projection.cjs");
+const { dispatchGsdCommand } = shellCommandProjection;
 exports.PROTOCOL_VERSION = '2024-11-05';
 exports.SERVER_NAME = 'gsd-core';
 const SERVER_VERSION = '1.7.0';
@@ -94,9 +103,11 @@ function callTool(name, args, ctx) {
             if (!family || !subcommand) {
                 return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
             }
-            const hub = commandRoutingHub.createHub();
-            const res = hub.dispatch({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd, raw: undefined });
-            return { content: [{ type: 'text', text: JSON.stringify(res) }] };
+            const res = dispatchGsdCommand({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd });
+            if (!res.ok) {
+                return { isError: true, content: [{ type: 'text', text: res.stderr || res.stdout || `dispatch failed (exit ${res.code})` }] };
+            }
+            return { content: [{ type: 'text', text: res.stdout }] };
         }
         if (name === 'gsd_read_state') {
             const p = asString(a.path);

package/gsd-core/bin/lib/milestone.cjs

@@ -26,7 +26,7 @@ const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseTokenMatches } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseTokenMatches, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo } = roadmapParserMod;
@@ -156,8 +156,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             if (stateVersion && stateVersion === version) {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
-                // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
+                // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
                 const noDirectoryPhases = [];
                 let pm;
                 const phaseDirEntries = (() => {