@opengsd/gsd-core 1.8.0 → 1.9.0

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -16,41 +16,108 @@
  * detected. The instance→cli mapping lives HERE (single source; see the parity
  * test in tests/review-reviewer-instances.test.cjs — DEFECT.GENERATIVE-FIX).
  *
- * KNOWN_REVIEWER_SLUGS (post-review #2092): registry-derived, not a flat
- * hand-maintained array. Each capability-runtime descriptor that is a valid
- * reviewer CLI declares `runtime.hostBehaviors.reviewerCli: true`
- * (capabilities/<id>/capability.json); this module reads that flag off the
- * generated capability-registry.cjs at require-time. A handful of reviewer
- * CLIs are NOT install-time runtimes at all (no capabilities/<id>/ descriptor
- * exists) — those stay a small hardcoded tail:
- *   - `gemini` — hook-event dialect name only (see runtime-hooks-surface.cts);
- *     the Gemini CLI reviewer is not an installable runtime (#1928 folded
- *     gemini into antigravity's descriptor).
- *   - `coderabbit` / `ollama` / `lm_studio` / `llama_cpp` — third-party
- *     review/model CLIs with no GSD install surface at all.
+ * KNOWN_REVIEWER_SLUGS (ADR-2782 D9, Phase 5a #2798): derived from declared
+ * `reviewer` bodies in the capability registry, not a hand-maintained tail.
+ * A capability of EITHER `role: "runtime"` (the six dual-purpose hosts —
+ * antigravity/claude/codex/cursor/opencode/qwen) or the lane-only
+ * `role: "reviewer"` (gemini/coderabbit/ollama/lm_studio/llama_cpp) may carry
+ * a `reviewer` body, and it is the body's `reviewer.slug` — NOT the capability
+ * id — that becomes the roster entry: the two differ for `lm-studio` (id) /
+ * `lm_studio` (slug) and `llama-cpp` (id) / `llama_cpp` (slug), ADR-2782's
+ * three-namespace trap (`id` must be kebab; `slug` keeps the shipped roster's
+ * snake form).
+ *
+ * `runtime.hostBehaviors.reviewerCli: true` survives as a DERIVED LEGACY ALIAS
+ * for one release (D9): a capability that only sets the flag (no `reviewer`
+ * body yet) still contributes its capability id as a slug, exactly as before
+ * this phase. Where a capability carries BOTH a declared body and the alias,
+ * the BODY WINS — that capability contributes only the body's slug, never
+ * both. Alias removal is a named later phase (#2801), not done here.
+ *
+ * Before this phase the five non-runtime reviewers (`gemini`, `coderabbit`,
+ * `ollama`, `lm_studio`, `llama_cpp`) had no `capabilities/<id>/` descriptor at
+ * all and were a hardcoded `NON_RUNTIME_REVIEWER_SLUGS` tail. Phase 5a gives
+ * each one a lane-only `role: "reviewer"` capability (ADR-2782 D3), so the
+ * tail is deleted outright. See
+ * `docs/adr/2782-reviewer-lane-capability-surface.md`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTANCE_NAME_PATTERN = exports.KNOWN_REVIEWER_SLUGS = void 0;
+exports.deriveReviewerSlugs = deriveReviewerSlugs;
 exports.normalizeConfiguredDefaultReviewers = normalizeConfiguredDefaultReviewers;
 exports.normalizeReviewerInstances = normalizeReviewerInstances;
 exports.resolveReviewerSelection = resolveReviewerSelection;
-const NON_RUNTIME_REVIEWER_SLUGS = [
-    'gemini',
-    'coderabbit',
-    'ollama',
-    'lm_studio',
-    'llama_cpp',
-];
-function deriveRuntimeReviewerSlugs() {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
-    const runtimes = registry.runtimes || {};
-    return Object.keys(runtimes).filter((id) => runtimes[id]?.runtime?.hostBehaviors?.reviewerCli === true);
+/**
+ * Derive the reviewer-slug roster from a capability registry.
+ *
+ * Exported (rather than a require()-time-only side effect) so tests can
+ * exercise the derivation directly against a synthetic registry — the real
+ * roster below is a single call against the generated
+ * `capability-registry.cjs`, and `tests/review-lane-descriptor.test.cjs`'s
+ * `checkReviewerLaneParity` separately guards that the real roster still
+ * agrees with `src/review-lane-descriptor.cts` and the workflow.
+ *
+ * Reads `registry.capabilities` — every declared capability regardless of
+ * role — because a `role: "reviewer"` lane-only capability is never stored in
+ * `registry.runtimes` (that map is role:"runtime" only). Per capability: a
+ * declared `reviewer.slug` wins outright (D9) and the capability contributes
+ * ONLY that slug; only when there is no body does the legacy
+ * `hostBehaviors.reviewerCli` alias contribute the capability id instead. The
+ * result is collected into a Set (so a slug can never appear twice, even if
+ * two distinct capabilities somehow named the same one) and returned as a
+ * SORTED array, so the roster's order never depends on `Object.entries()`
+ * iteration / registry build order.
+ */
+function deriveReviewerSlugs(registry) {
+    const capabilities = registry.capabilities || {};
+    const slugs = new Set();
+    for (const [capId, cap] of Object.entries(capabilities)) {
+        // Trim before the emptiness test: `length > 0` alone admits a whitespace-only
+        // slug ("   ") verbatim into the roster, where it can never match a real lane
+        // but still occupies a roster entry. Unreachable through the checked-in
+        // registry today, but this function is EXPORTED for reuse and carries no
+        // other validation, so it should not depend on its caller's hygiene.
+        const rawSlug = cap?.reviewer?.slug;
+        const declaredSlug = typeof rawSlug === 'string' ? rawSlug.trim() : '';
+        if (declaredSlug.length > 0) {
+            slugs.add(declaredSlug);
+            continue; // the body wins — never ALSO add this capability's alias below.
+        }
+        if (cap?.runtime?.hostBehaviors?.reviewerCli === true) {
+            slugs.add(capId);
+        }
+    }
+    return [...slugs].sort();
 }
-exports.KNOWN_REVIEWER_SLUGS = [
-    ...deriveRuntimeReviewerSlugs(),
-    ...NON_RUNTIME_REVIEWER_SLUGS,
-];
+/**
+ * The roster, derived once at module load.
+ *
+ * GUARDED, because this runs at `require()` time: an uncaught throw here does not
+ * degrade reviewer selection, it breaks `require()` of this module for EVERY
+ * consumer. The sibling `capability-trust.cjs` already holds this line — its
+ * `discloseExecutableSurfaces` is documented "TOTAL: never throws, for any
+ * manifest shape" and wrapped accordingly — and this module handles the same
+ * class of registry-derived input, so it should not be the asymmetric one.
+ *
+ * A malformed registry yields an EMPTY roster rather than a crash. That is a
+ * visible degradation, not a silent one: under ADR-2782 D4 an explicitly
+ * requested reviewer that is unavailable is an ERROR, so `/gsd:review --claude`
+ * against an empty roster fails loudly instead of quietly reviewing with nobody.
+ *
+ * Unreachable through the checked-in registry today (it is generated, JSON-sourced
+ * and code-reviewed, so it cannot carry a getter or a Proxy). Guarded anyway —
+ * reachability analysis is not a contract, and the next caller should not have to
+ * redo it.
+ */
+exports.KNOWN_REVIEWER_SLUGS = (() => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return deriveReviewerSlugs(require('./capability-registry.cjs'));
+    }
+    catch {
+        return [];
+    }
+})();
 /** Instance names are lowercase slugs that must not shadow a built-in slug. */
 exports.INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function normalizeConfiguredDefaultReviewers(rawValue) {
@@ -164,12 +231,27 @@ function resolveReviewerSelection(input) {
     let selected = [];
     if (explicitFlags.size > 0) {
         source = 'explicit_flags';
+        // ADR-2782 D4: absent-safe governs DISCOVERY, never explicit selection.
+        // Not finding a lane nobody asked for is normal; failing to run a lane
+        // somebody asked for is an error. Every miss used to be an `info`, so a
+        // PARTIAL miss (`--gemini --qwen` with qwen absent) ran the review with a
+        // thinner reviewer set while present_results reported success — "a cross-AI
+        // review that silently drops a lane is blind in one eye" (review.md).
+        // A total miss already errored, but only as a side effect of the selected
+        // set being empty; the partial case had no signal at all.
+        const priorErrorCount = errors.length;
         selected = [...explicitFlags].filter((slug) => detected.has(slug));
-        const missing = [...explicitFlags].filter((slug) => !detected.has(slug));
-        if (missing.length > 0) {
-            infos.push(`explicit reviewers missing on host: ${missing.join(', ')}`);
+        // Sorted so the error order does not depend on flag order on the command line.
+        const missing = [...explicitFlags].filter((slug) => !detected.has(slug)).sort();
+        for (const slug of missing) {
+            errors.push(`explicit reviewer '${slug}' is not available on this host`);
         }
-        if (selected.length === 0 && errors.length === 0) {
+        // Guarded on the error count as it stood BEFORE this branch, so the
+        // aggregate message fires under exactly the conditions it did previously.
+        // Guarding on `errors.length` would let the per-slug errors just pushed
+        // suppress it, silently dropping a message this change did not intend to
+        // remove.
+        if (selected.length === 0 && priorErrorCount === 0) {
             errors.push('no selected reviewers are available for explicit flags');
         }
     }

package/gsd-core/bin/lib/roadmap-parser.cjs

@@ -31,6 +31,9 @@ roadmapPhaseLookupSources, } = phaseIdModule;
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInputMod = require("./unusable-input.cjs");
+const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Roadmap milestone scoping ───────────────────────────────────────────────
 /**
@@ -271,10 +274,18 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     const normalizedPhase = stripProjectCodePrefix(phaseNum);
     if (/^999(?:\.|$)/.test(normalizedPhase))
         return null;
-    const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-    if (!node_fs_1.default.existsSync(roadmapPath))
-        return null;
+    // Resolved INSIDE the try for the same reason as getMilestoneInfo below: planningDir
+    // throws a plain Error for an invalid GSD_WORKSTREAM/GSD_PROJECT segment, and resolving
+    // it outside let that escape uncaught, crashing every caller for a malformed workstream
+    // name. ADR-227 is explicit that throwing breaks pipeline continuity, and this read path
+    // has no reason to be the exception -- it already degrades to null for every other
+    // failure. Absence still returns null before any diagnostic, and when the path never
+    // resolved there is nothing to name.
+    let roadmapPath;
     try {
+        roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+        if (!node_fs_1.default.existsSync(roadmapPath))
+            return null;
         const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmapRaw === null)
             throw new Error('missing');
@@ -301,10 +312,33 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
         }
         return null;
     }
-    catch {
+    catch (err) {
+        // Absence already returned above via existsSync; anything caught here is a read fault
+        // or the synthetic missing-marker. The null is preserved exactly either way.
+        if (roadmapPath !== undefined)
+            reportUnreadableRoadmap(err, roadmapPath);
         return null;
     }
 }
+/**
+ * Report a ROADMAP.md that exists but could not be read (#1881, ADR-1411).
+ *
+ * The discriminator is the errno, and it matters in the SILENT direction.
+ * platformReadSync returns null for ENOENT and both callers convert that null into a
+ * synthetic Error carrying no code, which lands in the same catch as a real EACCES.
+ * Reporting unconditionally here would flag every project that has no ROADMAP.md yet --
+ * every brand-new project -- as corrupt. A genuine read fault always carries an errno;
+ * absence never does.
+ *
+ * The parse itself is regex over text and cannot throw, so anything reaching a catch is
+ * either a read fault or that synthetic absence marker. Nothing else gets here.
+ */
+function reportUnreadableRoadmap(err, roadmapPath) {
+    const code = err?.code;
+    if (typeof code !== 'string')
+        return;
+    warnUnusableInput({ reason: UNUSABLE_REASON.ROADMAP_UNREADABLE, source: roadmapPath });
+}
 /**
  * Strip a leading delimiter run (whitespace, em/en-dash, colon, hyphen) from a
  * milestone-name capture. Markdown headings commonly take the shape
@@ -318,8 +352,16 @@ function stripLeadingDelimiter(s) {
     return s.replace(/^[\s—–:-]+/, '').trim();
 }
 function getMilestoneInfo(cwd) {
+    // Declared here but RESOLVED INSIDE the try, so the catch can name the file without
+    // moving planningDir() out of the protected region. planningDir throws a plain Error
+    // for an invalid GSD_WORKSTREAM/GSD_PROJECT segment, and hoisting the call let that
+    // escape uncaught — breaking the invariant #2245 relies on, that this function never
+    // throws. When the path never resolved there is nothing to name, so the diagnostic is
+    // skipped and the default is returned exactly as before.
+    let roadmapPath;
     try {
-        const roadmap = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
+        roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+        const roadmap = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmap === null)
             throw new Error('missing');
         let stateVersion = null;
@@ -388,7 +430,13 @@ function getMilestoneInfo(cwd) {
             name: 'milestone',
         };
     }
-    catch {
+    catch (err) {
+        // This function has no existsSync guard, so an absent ROADMAP arrives here too, as a
+        // synthetic Error with no errno. Only a real read fault is reported; the populated
+        // default is returned unchanged either way, and a plausible-looking default needs the
+        // diagnostic more than an empty sentinel does, not less (ADR-1411).
+        if (roadmapPath !== undefined)
+            reportUnreadableRoadmap(err, roadmapPath);
         return { version: 'v1.0', name: 'milestone' };
     }
 }

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

@@ -137,10 +137,16 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
     // comparison; unrecognized values are preserved verbatim for forward-compat.
     const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
     const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
-    // Extract success criteria as structured array
-    const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
+    // Extract success criteria as structured array. A criterion may wrap onto extra
+    // indented lines (no `N.` prefix); those continuations must fold INTO their
+    // criterion, not end the run (#2522 — the old `(?:\s*\d+\.\s*[^\n]+)+` broke on a
+    // wrapped line, truncating it and silently dropping every criterion below it).
+    // `\n*` before each numbered line keeps blank-line-separated criteria working.
+    const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\n*[ \t]*\d+\.[^\n]*\n?(?:[ \t]+(?!\d+\.)[^\n]*\n?)*)+)/i);
     const success_criteria = criteriaMatch
-        ? criteriaMatch[1].trim().split('\n').map(line => line.replace(/^\s*\d+\.\s*/, '').trim()).filter(Boolean)
+        ? criteriaMatch[1].trim().split(/\n+(?=[ \t]*\d+\.)/)
+            .map(entry => entry.replace(/^\s*\d+\.\s*/, '').replace(/\s*\n\s*/g, ' ').trim())
+            .filter(Boolean)
         : [];
     return {
         found: true,
@@ -658,7 +664,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         const planPath = node_path_1.default.join(node_path_1.default.resolve(cwd, phaseInfo.directory), planFile);
         try {
             const content = node_fs_1.default.readFileSync(planPath, 'utf-8');
-            const fm = extractFrontmatter(content);
+            const fm = extractFrontmatter(content, planPath);
             const wave = parseInt(fm.wave, 10) || 1;
             const planId = planFile.replace(/-PLAN\.md$/i, '').replace(/PLAN\.md$/i, '');
             const truths = parseMustHavesBlock(content, 'truths') || [];

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

@@ -518,6 +518,28 @@ function convertClaudeCommandToKimiSkill(content, skillName, _runtime = null, cm
     const normalizedBody = convertGsdCommandReferencesToKimiSkillInvocations(frontmatter ? body : content, names);
     return `---\nname: ${kimiSkillName}\ndescription: ${yamlQuote(toSingleLine(description))}\n---\nInvoke this Kimi skill with \`/skill:${kimiSkillName}\`.\n\n${normalizedBody}`;
 }
+/**
+ * Convert a Claude command-markdown source into a Kimi Code Agent Skill.
+ *
+ * Kimi Code (Moonshot's Node CLI) uses the standard Agent Skills format —
+ * a directory containing SKILL.md with frontmatter (name/description) and
+ * body — auto-discovered from `~/.kimi-code/skills/` (per Kimi Code docs:
+ * "Agent Skills is an open format for adding specialized knowledge and
+ * workflows to AI agents"). The invocation prefix is `/skill:<name>`,
+ * identical to Python kimi-cli.
+ *
+ * Today the output is byte-identical to `convertClaudeCommandToKimiSkill`
+ * (the Python kimi-cli converter) because both products consume the same
+ * Agent Skills format + `/skill:` invocation. The distinct function name
+ * lets a future divergence land cleanly if Kimi Code's skill format evolves
+ * independently of Python kimi-cli.
+ *
+ * Registered as `convertClaudeCommandToKimiCodeSkill` in the capabilities/
+ * kimi-code/capability.json `artifactLayout` `converter` field (#2454 PR 2).
+ */
+function convertClaudeCommandToKimiCodeSkill(content, skillName, _runtime = null, cmdNames = null) {
+    return convertClaudeCommandToKimiSkill(content, skillName, _runtime, cmdNames);
+}
 const KIMI_CANONICAL_GSD_AGENT_RE = /^gsd-[a-z0-9-]+$/;
 function parseKimiAgentSource(source) {
     if (typeof source === 'string') {
@@ -1391,10 +1413,14 @@ Typed mapping (agent_type-capable schema only):
   inherited, or unsupported values; do not invent one-off effort literals in
   workflow prose.
 - \`fork_context: false\` by default — GSD agents load their own context via \`<files_to_read>\` blocks
-- \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct Codex mapping.
-  Codex \`spawn_agent\` does not create or bind a git worktree automatically.
-  Workflows that require this isolation must fail closed or use an explicit
-  manual worktree protocol before spawning (#3360).
+- \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct \`spawn_agent\` mapping,
+  but Codex declares \`dispatch.isolation: orchestrator-worktree\` (#2584). Codex
+  \`spawn_agent\` still does not create or bind a git worktree; instead GSD itself
+  creates the worktree and process-spawns the executor into it with
+  \`codex exec --cd <dir>\`, performing every git operation on the executor's behalf
+  (its \`workspace-write\` sandbox makes \`.git\` read-only). Workflows must therefore
+  never fabricate a manual worktree protocol — route through the negotiated
+  isolation adapter, which still fails closed for hosts declaring \`none\` (#3360).
 
 Generic-agent workaround (multi_agent_v1 schema — NO agent_type field):
 When only the generic \`multi_agent_v1\` schema is available, typed GSD agent dispatch
@@ -2603,6 +2629,7 @@ module.exports = {
     convertClaudeCommandToAntigravitySkill,
     convertClaudeCommandToClaudeSkill,
     convertClaudeCommandToKimiSkill,
+    convertClaudeCommandToKimiCodeSkill,
     buildKimiAgentArtifacts,
     convertClaudeToCursorMarkdown,
     convertClaudeCommandToCursorSkill,

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

@@ -316,7 +316,7 @@ function dispatchKindEntry(entry, runtime, configDir, scope, capabilityRegistry)
         default:
             throw new TypeError(`resolveRuntimeArtifactLayout: unknown kind '${kind}' in descriptor for runtime '${runtime}'`);
     }
-    if (typeof entry.home === 'string' && entry.home !== '') {
+    if (scope === 'global' && typeof entry.home === 'string' && entry.home !== '') {
         result.home = node_path_1.default.join(node_os_1.default.homedir(), entry.home);
     }
     return result;

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -149,6 +149,81 @@ function atomicWriteFileSync(target, data, options) {
     }
 }
 // ---------------------------------------------------------------------------
+// CommonJS package.json marker for staged .js hook scripts (#2717)
+//
+// Node resolves the nearest package.json walking up from a .js file. When a
+// runtime's config root (e.g. ~/.cursor, ~/.codeium/windsurf, ~/.codex) — or any
+// parent — declares {"type":"module"}, Node loads GSD's staged CommonJS hook
+// scripts as ESM and every require() fails with "require is not defined",
+// silently disabling that runtime's lifecycle hooks.
+//
+// installSharedHooksBundle writes this marker for the 12 runtimes that go
+// through the shared hooks bundle, but cursor/windsurf (skipSharedHooksInstall)
+// and codex (the !isCodex gate) stage their .js hooks via the dedicated paths
+// below and never reached it. These helpers decouple the marker write from the
+// shared bundle so any code path that stages .js hooks can ensure the marker
+// lands in the SAME directory as the scripts (#2717).
+//
+// The marker content is byte-identical to installSharedHooksBundle's
+// (bin/install.js installSharedHooksBundle): {"type":"commonjs"}\n.
+// ---------------------------------------------------------------------------
+/** The exact marker content GSD writes, matching installSharedHooksBundle. */
+const COMMONJS_MARKER_CONTENT = '{"type":"commonjs"}\n';
+/**
+ * Ensure a `package.json` forcing CommonJS mode exists in `dir` (the directory
+ * holding GSD-staged `.js` hook scripts). Idempotent: a no-op if the marker is
+ * already present with GSD's content. Overwrites only when the file is absent
+ * or already carries GSD's exact marker — it never clobbers a distinct
+ * user-authored package.json (it leaves such a file in place; the user owns it).
+ *
+ * @param dir - absolute path to the directory holding the staged .js hooks
+ * @returns `true` if the marker is present after the call (written or already there)
+ */
+function ensureCommonJsMarker(dir) {
+    const markerPath = node_path_1.default.join(dir, 'package.json');
+    try {
+        if (node_fs_1.default.existsSync(markerPath)) {
+            const existing = node_fs_1.default.readFileSync(markerPath, 'utf8');
+            // Already GSD's marker (tolerant of trailing-whitespace variants) — done.
+            if (existing.trim() === '{"type":"commonjs"}')
+                return true;
+            // A distinct package.json the user owns — do NOT clobber. The hook will
+            // load as whatever type the user declared; that is the user's choice.
+            return false;
+        }
+        node_fs_1.default.writeFileSync(markerPath, COMMONJS_MARKER_CONTENT);
+        return true;
+    }
+    catch {
+        // Best-effort: a marker write failure must not fail the whole install.
+        return false;
+    }
+}
+/**
+ * Remove the CommonJS marker from `dir` on uninstall — but ONLY if it carries
+ * GSD's exact marker content. A user-authored package.json is never deleted.
+ * Mirrors the kimi uninstall guard in bin/install.js.
+ *
+ * @param dir - absolute path to the directory that held the staged .js hooks
+ * @returns `true` if a GSD-owned marker was removed
+ */
+function removeCommonJsMarkerIfGsdOwned(dir) {
+    const markerPath = node_path_1.default.join(dir, 'package.json');
+    try {
+        if (!node_fs_1.default.existsSync(markerPath))
+            return false;
+        const content = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        if (content === '{"type":"commonjs"}') {
+            node_fs_1.default.unlinkSync(markerPath);
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
 // parseTomlValue + findMultilineBasicStringClose
 // (needed by rewriteLegacyCodexHookBlock — pure TOML helpers, no state)
 // ---------------------------------------------------------------------------
@@ -956,6 +1031,48 @@ function writeCursorHooksJson(targetDir, src, opts) {
             installedScripts.add(script);
         }
     }
+    // Stage the hooks/lib/ helpers the staged scripts require (#2587). Cursor sets
+    // hostBehaviors.skipSharedHooksInstall, so it never reaches the installer's
+    // bulk hooks/lib copy — without this, a script requiring './lib/…' would throw
+    // MODULE_NOT_FOUND at load, BEFORE its own try/catch, and wedge every Cursor
+    // session on the one runtime these hooks exist for. Driven off what the staged
+    // scripts actually require so a future helper cannot be silently omitted.
+    const requiredLibFiles = new Set();
+    for (const script of installedScripts) {
+        const staged = node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8');
+        // Tolerant of interior whitespace and either quote style: a hook author
+        // writing `require( "./lib/x.js" )` must still get its helper staged, since
+        // a miss here surfaces as MODULE_NOT_FOUND at hook load, not at install.
+        const re = /require\(\s*['"]\.\/lib\/([A-Za-z0-9._-]+)['"]\s*\)/g;
+        let m;
+        while ((m = re.exec(staged)) !== null)
+            requiredLibFiles.add(m[1]);
+    }
+    if (requiredLibFiles.size > 0) {
+        const srcLibDir = node_path_1.default.join(srcHooksDir, 'lib');
+        const destLibDir = node_path_1.default.join(hooksDir, 'lib');
+        node_fs_1.default.mkdirSync(destLibDir, { recursive: true });
+        for (const libFile of requiredLibFiles) {
+            const libSrc = node_path_1.default.join(srcLibDir, libFile);
+            if (!node_fs_1.default.existsSync(libSrc)) {
+                // FAIL LOUD. Skipping here would ship hook scripts whose top-level
+                // require() throws before their own try/catch, wedging every session —
+                // and the install would still exit 0, so nobody would know until a user
+                // hit it. A missing helper source is a packaging bug; surface it.
+                throw new Error(`hooks/lib/${libFile} is required by a staged Cursor hook but is missing from ${srcLibDir}. `
+                    + 'Installing would ship a hook that throws MODULE_NOT_FOUND at load.');
+            }
+            let libContent = node_fs_1.default.readFileSync(libSrc, 'utf8');
+            libContent = libContent.replace(/gsd:/gi, 'gsd-');
+            node_fs_1.default.writeFileSync(node_path_1.default.join(destLibDir, libFile), libContent);
+        }
+    }
+    // #2717: write the CommonJS marker into hooks/ alongside the staged .js
+    // scripts. Cursor sets skipSharedHooksInstall, so it never reaches
+    // installSharedHooksBundle (the only other writer of this marker); without
+    // it, a ~/.cursor/package.json declaring {"type":"module"} makes Node load
+    // these require()-using scripts as ESM and every Cursor hook fails silently.
+    ensureCommonJsMarker(hooksDir);
     const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of events) {
@@ -987,6 +1104,14 @@ function removeCursorHooksJson(targetDir) {
             const hasAnyEvents = Object.keys(hookTable).some((k) => Array.isArray(hookTable[k]) && hookTable[k].length > 0);
             if (!hasAnyEvents) {
                 node_fs_1.default.unlinkSync(hooksJsonPath);
+                // #2717: also remove the CommonJS marker GSD wrote into hooks/ — but
+                // only if it still carries GSD's exact content (a user-authored
+                // package.json is never deleted). Best-effort: a failure here must not
+                // mask the hooks.json removal above.
+                try {
+                    removeCommonJsMarkerIfGsdOwned(node_path_1.default.join(targetDir, 'hooks'));
+                }
+                catch { /* leave it */ }
                 return { changed: true };
             }
         }
@@ -1136,6 +1261,12 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
             installedScripts.add(script);
         }
     }
+    // #2717: write the CommonJS marker into hooks/ alongside the staged .js
+    // scripts. Windsurf sets skipSharedHooksInstall, so it never reaches
+    // installSharedHooksBundle (the only other writer of this marker); without
+    // it, a config-root package.json declaring {"type":"module"} makes Node load
+    // these require()-using scripts as ESM and the Windsurf hooks fail silently.
+    ensureCommonJsMarker(hooksDir);
     const hookOpts = { runtime: 'windsurf', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of WINDSURF_HOOK_EVENTS) {
@@ -1174,6 +1305,13 @@ function removeWindsurfHooksJson(targetDir) {
             const hasAnyEvents = Object.keys(hookTable).some((k) => Array.isArray(hookTable[k]) && hookTable[k].length > 0);
             if (!hasAnyEvents) {
                 node_fs_1.default.unlinkSync(hooksJsonPath);
+                // #2717: also remove the CommonJS marker GSD wrote into hooks/ — but
+                // only if it still carries GSD's exact content (a user-authored
+                // package.json is never deleted). Best-effort.
+                try {
+                    removeCommonJsMarkerIfGsdOwned(node_path_1.default.join(targetDir, 'hooks'));
+                }
+                catch { /* leave it */ }
                 return { changed: true };
             }
         }
@@ -1963,6 +2101,8 @@ module.exports = {
     GSD_WINDSURF_PRE_WRITE_HOOK_SCRIPT,
     GSD_WINDSURF_PRE_COMMAND_HOOK_SCRIPT,
     GSD_WINDSURF_HOOK_SCRIPTS,
+    ensureCommonJsMarker,
+    removeCommonJsMarkerIfGsdOwned,
     GSD_WINDSURF_HOOK_MARKER,
     // Copilot
     buildCopilotHookConfig,

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -40,6 +40,7 @@ const FALLBACK_ALIASES = {
     qwen: ['qwen', 'qwen-code', 'qwen-cli'],
     hermes: ['hermes', 'hermes-agent', 'hermes-cli'],
     kimi: ['kimi'],
+    'kimi-code': ['kimi-code', 'kimicode', 'kimi_code'],
     codebuddy: ['codebuddy', 'codebuddy-cli'],
     cline: ['cline', 'cline-cli'],
 };
@@ -248,6 +249,7 @@ const RUNTIME_LABELS = {
     qwen: 'Qwen Code',
     hermes: 'Hermes Agent',
     kimi: 'Kimi CLI',
+    'kimi-code': 'Kimi Code',
     codebuddy: 'CodeBuddy',
     cline: 'Cline',
     zcode: 'ZCode',
@@ -303,6 +305,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
     codebuddy: "'.codebuddy'",
     cline: "'.cline'",
     kimi: "'.config', 'agents'",
+    'kimi-code': "'.kimi-code'",
     zcode: "'.zcode'",
     // pi's global config home is ~/.pi/agent (configHome: dot-home-nested,
     // parent '.pi', name 'agent' — capabilities/pi/capability.json), matching
@@ -337,8 +340,18 @@ function getGlobalConfigHomeFragment(runtime) {
 // folds the shared-hooks-install skip).
 const RUNTIME_FLAG_IDS = Object.freeze([
     'opencode', 'kilo', 'codex', 'copilot', 'antigravity', 'cursor',
-    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode', 'pi',
+    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'kimi-code', 'zcode', 'pi',
 ]);
+/**
+ * Convert a runtime id (kebab-case, e.g. 'kimi-code') to its `is<Foo>` flag
+ * name in PascalCase (e.g. 'isKimiCode'). The first letter is capitalised and
+ * every `-[a-z]` boundary is folded to its uppercase twin. Single-word ids
+ * (the prior 16: opencode, kilo, codex, …) are unaffected — only hyphenated
+ * ids like 'kimi-code' (#2454) hit the folding branch.
+ */
+function runtimeIdToFlagName(id) {
+    return 'is' + id.charAt(0).toUpperCase() + id.slice(1).replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
 /**
  * Return a frozen map of `is<Runtime>` boolean predicates for the given runtime
  * id (e.g. `flags.isOpencode`). Collapses the four duplicated `const isX =
@@ -349,7 +362,7 @@ const RUNTIME_FLAG_IDS = Object.freeze([
 function runtimeFlags(runtime) {
     const flags = {};
     for (const id of RUNTIME_FLAG_IDS) {
-        flags['is' + id.charAt(0).toUpperCase() + id.slice(1)] = runtime === id;
+        flags[runtimeIdToFlagName(id)] = runtime === id;
     }
     return Object.freeze(flags);
 }

package/gsd-core/bin/lib/smart-entry.cjs

@@ -224,7 +224,7 @@ function readStateFile(statePath) {
     catch {
         return null;
     }
-    const fm = extractFrontmatter(content);
+    const fm = extractFrontmatter(content, statePath);
     const body = content.replace(/^---[\s\S]*?---\s*/, '');
     return { fm, body };
 }