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

package/gsd-core/bin/lib/install-effort-resolver.cjs

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * install-effort-resolver — install-time effort resolution (#443), extracted from
+ * the package-root `bin/install.js` (#2071).
+ *
+ * `gsd-tools effort sync` (src/commands.cts `cmdEffortSync`) must mirror what the
+ * installer writes — home `~/.gsd/defaults.json` merged with the project's
+ * `.planning/config.json` — which the runtime resolver (`resolveEffortInternal`
+ * via `loadConfig`) does NOT do. It previously reached those two functions via
+ * `require('../../../bin/install.js')`, but the installer never copies the
+ * package-root `bin/install.js` into a runtime home, so `effort sync` crashed with
+ * MODULE_NOT_FOUND in every installed runtime (#2071). Moving the logic here — a
+ * `src/*.cts` module compiled into the shipped `gsd-core/bin/lib/` tree — lets both
+ * the installer AND `effort sync` require it from a location that is always present,
+ * keeping a single source of truth (no duplication / drift).
+ *
+ * Pure with respect to config: `readGsdEffectiveEffortConfig` performs the config
+ * reads; `resolveInstallTimeEffort` is pure given a pre-merged effort object.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
+const modelResolver = require("./model-resolver.cjs");
+const { EFFORT_SET: GSD_EFFORT_SET } = modelResolver;
+/**
+ * #2517 — Read a single GSD config file (defaults.json or per-project
+ * config.json) into a plain object, returning null on missing/empty files
+ * and warning to stderr on JSON parse failures so silent corruption can't
+ * mask broken configs (review finding #5).
+ */
+function _readGsdConfigFile(absPath, label) {
+    if (!node_fs_1.default.existsSync(absPath))
+        return null;
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(absPath, 'utf-8');
+    }
+    catch (err) {
+        process.stderr.write(`gsd: warning — could not read ${label} (${absPath}): ${err.message}\n`);
+        return null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`gsd: warning — invalid JSON in ${label} (${absPath}): ${err.message}\n`);
+        return null;
+    }
+}
+// #443 — model-catalog and config-defaults.manifest.json exports needed only
+// by effort-resolution code paths (resolveInstallTimeEffort /
+// generateCodexAgentToml / Claude .md effort injection).  Loaded lazily the
+// first time they are needed so that requiring this module in test contexts that
+// never trigger an install does NOT produce module-load-time side effects (the
+// manifest read + hard throw) that could alter subprocess exit codes or stderr.
+let _gsdEffortCatalogCache = null;
+function _getGsdEffortCatalog() {
+    if (_gsdEffortCatalogCache)
+        return _gsdEffortCatalogCache;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- model-catalog.cjs is an export= CommonJS module
+    const { AGENT_DEFAULT_TIERS, renderEffortForRuntime } = require('./model-catalog.cjs');
+    // This module lives in gsd-core/bin/lib/, so the shared manifest is one level
+    // up in gsd-core/bin/shared/ (bin/lib → bin → shared). (In bin/install.js this
+    // path was `.., gsd-core, bin, shared` relative to the package-root bin/.)
+    const manifestPath = node_path_1.default.join(__dirname, '..', 'shared', 'config-defaults.manifest.json');
+    let manifestData;
+    try {
+        manifestData = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch (_err) {
+        // Fail loudly — a missing manifest is a broken install, not a soft degradation.
+        throw new Error(`gsd install: cannot load config-defaults.manifest.json at ${manifestPath}: ${_err.message}`);
+    }
+    const tierDefaults = (manifestData.effort &&
+        manifestData.effort.routing_tier_defaults &&
+        typeof manifestData.effort.routing_tier_defaults === 'object' &&
+        !Array.isArray(manifestData.effort.routing_tier_defaults))
+        ? manifestData.effort.routing_tier_defaults
+        : { light: 'low', standard: 'high', heavy: 'xhigh' }; // guard: unreachable if manifest is valid
+    const effortDefault = (manifestData.effort && typeof manifestData.effort.default === 'string')
+        ? manifestData.effort.default
+        : 'high'; // guard: unreachable if manifest is valid
+    _gsdEffortCatalogCache = {
+        AGENT_DEFAULT_TIERS,
+        renderEffortForRuntime,
+        EFFORT_MANIFEST_TIER_DEFAULTS: tierDefaults,
+        EFFORT_MANIFEST_DEFAULT: effortDefault,
+    };
+    return _gsdEffortCatalogCache;
+}
+/**
+ * #443 — Read the merged `effort` config block for install-time effort resolution.
+ *
+ * Probes the same config sources as readGsdRuntimeProfileResolver (per-project
+ * `.planning/config.json` wins over `~/.gsd/defaults.json`) but extracts the
+ * `effort` object instead of the model-profile fields.
+ *
+ * Returns the merged `effort` object or null when neither source defines one.
+ * The caller can pass this to resolveInstallTimeEffort() which is pure and
+ * requires no filesystem access beyond what this helper already performs.
+ *
+ * @param targetDir  Runtime install root (walks up to find .planning/).
+ */
+function readGsdEffectiveEffortConfig(targetDir = null) {
+    const homeDefaults = _readGsdConfigFile(node_path_1.default.join(node_os_1.default.homedir(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
+    let projectConfig = null;
+    if (targetDir) {
+        let probeDir = node_path_1.default.resolve(targetDir);
+        for (let depth = 0; depth < 8; depth += 1) {
+            const candidate = node_path_1.default.join(probeDir, '.planning', 'config.json');
+            if (node_fs_1.default.existsSync(candidate)) {
+                projectConfig = _readGsdConfigFile(candidate, '.planning/config.json');
+                break;
+            }
+            const parent = node_path_1.default.dirname(probeDir);
+            if (parent === probeDir)
+                break;
+            probeDir = parent;
+        }
+    }
+    const homeEffort = (homeDefaults && homeDefaults.effort && typeof homeDefaults.effort === 'object' && !Array.isArray(homeDefaults.effort))
+        ? homeDefaults.effort
+        : null;
+    const projectEffort = (projectConfig && projectConfig.effort && typeof projectConfig.effort === 'object' && !Array.isArray(projectConfig.effort))
+        ? projectConfig.effort
+        : null;
+    if (!homeEffort && !projectEffort)
+        return null;
+    // Per-project wins on conflict within each sub-field. Merge field-by-field so
+    // a project config that only sets agent_overrides still inherits global
+    // routing_tier_defaults and default.
+    return {
+        ...(homeEffort || {}),
+        ...(projectEffort || {}),
+        // Deep-merge agent_overrides (project wins per-key)
+        agent_overrides: {
+            ...((homeEffort && homeEffort.agent_overrides) || {}),
+            ...((projectEffort && projectEffort.agent_overrides) || {}),
+        },
+    };
+}
+/**
+ * #443 — Resolve install-time effort for a given agent, using the same
+ * precedence chain as resolveEffortInternal() in core.cjs, but operating
+ * on a pre-loaded effortCfg object (no loadConfig side-effects at install).
+ *
+ * Precedence (mirrors resolveEffortInternal):
+ *   1. effortCfg.agent_overrides[agentName]
+ *   2. effortCfg.routing_tier_defaults[agentTier]  (if effortCfg present)
+ *      — OR manifest tier defaults when effortCfg is null
+ *   3. effortCfg.default
+ *   4. 'high' (hardcoded fallback)
+ *
+ * @param effortCfg   Result of readGsdEffectiveEffortConfig().
+ * @param agentName   e.g. 'gsd-planner'
+ * @returns           Universal effort string (low/medium/high/xhigh/max/minimal)
+ */
+function resolveInstallTimeEffort(effortCfg, agentName) {
+    // Validates each candidate against the canonical EFFORT_SET (sourced once
+    // from model-resolver.cjs) before accepting it, mirroring resolveEffortInternal
+    // exactly. Invalid values fall through to the next precedence layer; final
+    // fallback 'high'.
+    // Step 1: agent_overrides
+    if (effortCfg) {
+        const ao = effortCfg.agent_overrides;
+        if (ao && typeof ao === 'object' && !Array.isArray(ao)) {
+            const v = ao[agentName];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+    }
+    // Step 2: routing_tier_defaults keyed by the agent's catalog tier
+    const { AGENT_DEFAULT_TIERS, EFFORT_MANIFEST_TIER_DEFAULTS, EFFORT_MANIFEST_DEFAULT } = _getGsdEffortCatalog();
+    const agentTier = AGENT_DEFAULT_TIERS[agentName];
+    if (agentTier) {
+        if (effortCfg && effortCfg.routing_tier_defaults &&
+            typeof effortCfg.routing_tier_defaults === 'object' &&
+            !Array.isArray(effortCfg.routing_tier_defaults)) {
+            const v = effortCfg.routing_tier_defaults[agentTier];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+        else if (!effortCfg) {
+            // No effort config — use manifest tier defaults
+            const v = EFFORT_MANIFEST_TIER_DEFAULTS[agentTier];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+        // effortCfg exists but has no routing_tier_defaults — fall through
+    }
+    // Step 3: effort.default
+    if (effortCfg) {
+        const d = effortCfg.default;
+        if (typeof d === 'string' && GSD_EFFORT_SET.has(d))
+            return d;
+    }
+    // Step 4: manifest default (sourced from config-defaults.manifest.json effort.default)
+    // If even the manifest default is invalid, fall back to 'high'.
+    if (typeof EFFORT_MANIFEST_DEFAULT === 'string' && GSD_EFFORT_SET.has(EFFORT_MANIFEST_DEFAULT)) {
+        return EFFORT_MANIFEST_DEFAULT;
+    }
+    return 'high';
+}
+module.exports = {
+    readGsdEffectiveEffortConfig,
+    resolveInstallTimeEffort,
+    _getGsdEffortCatalog,
+    _readGsdConfigFile,
+};

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
 // ---------------------------------------------------------------------------
 /**
@@ -231,14 +251,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;
@@ -519,6 +545,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 +578,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)) {
@@ -638,7 +679,7 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     const rawDir = rawCommandsDir;
     if (!rawDir || !node_fs_1.default.existsSync(rawDir))
         return 0;
-    const converter = runtime === 'kilo'
+    const converter = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
         ? convertClaudeCommandToKiloSkill
         : convertClaudeCommandToOpencodeSkill;
     const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
@@ -686,6 +727,102 @@ 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));
+            content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
+                ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
+                : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, destName), content);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// installOpencodeFamilyArtifacts
+// ---------------------------------------------------------------------------
+/**
+ * Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087).
+ * Stages the flattened commands surface + skills surface + (OpenCode only)
+ * 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);
+    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));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // uninstallRuntimeArtifacts
 // ---------------------------------------------------------------------------
 /**
@@ -740,6 +877,9 @@ module.exports = {
     installRuntimeArtifacts,
     uninstallRuntimeArtifacts,
     installOpencodeFamilySkills,
+    installOpencodeFamilyCommands,
+    installOpencodeFamilyArtifacts,
+    _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,
     preserveUserArtifacts,

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

@@ -37,7 +37,11 @@ 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',
     '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