@opengsd/gsd-core 1.16.0 → 1.18.0

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

@@ -20,6 +20,8 @@ const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const io = require("./io.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- capability-ledger.cjs is an export= CommonJS module
+const capabilityLedger = require("./capability-ledger.cjs");
 const project_root_cjs_1 = require("./project-root.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
 const modelResolver = require("./model-resolver.cjs");
@@ -157,6 +159,24 @@ function slugifyPhaseName(phaseName) {
     // the same reported phase_slug.
     return phaseName ? coreUtils.generateSlugInternal(phaseName, null) : null;
 }
+/**
+ * #4854: the one place that decides which name an `init` verb emits as
+ * `phase_name`. When a phase directory exists, `searchPhaseInDir` derives
+ * `phaseInfo.phase_name` from the directory-name remainder — already slugified
+ * (`phase.add` writes `${num}-${slug}` dirs), so it comes out byte-identical to
+ * `phase_slug`. The ROADMAP carries the curated display name
+ * (`### Phase N: <Name>`), so it wins; the disk-derived name is the fallback
+ * for a phase the ROADMAP does not describe, then `null`. #3171 fixed this
+ * inline for `init execute-phase` only; plan-phase (whose `phase_name` reaches
+ * STATE.md through `state planned-phase --name`), verify-work, code-review,
+ * discuss-phase-assumptions and phase-op read the raw disk value. `phase_slug`
+ * is deliberately not routed through here — it stays disk-derived.
+ */
+function resolvePhaseDisplayName(phaseInfo, roadmapPhase) {
+    return roadmapPhase?.['phase_name']
+        || phaseInfo?.['phase_name']
+        || null;
+}
 /**
  * #2994 (review finding, DEFECT.GENERATIVE-FIX): shared archived/not-found
  * fallback applied identically by `cmdInitExecutePhase`, `cmdInitPlanPhase`,
@@ -164,10 +184,11 @@ function slugifyPhaseName(phaseName) {
  * `cmdInitDiscussPhaseAssumptions` — 6 call sites previously reproducing the
  * exact same two-branch control flow verbatim (only the synthetic
  * replacement object's field set differs per caller, supplied here via
- * `buildFallback`). `cmdInitPhaseOp` is deliberately left untouched (CRITICAL
- * blast radius, 179 dependents) even though it follows the same shape, since
- * its own fallback object differs by one field (`has_reviews` absent) and is
- * not a byte-identical copy.
+ * `buildFallback`). `cmdInitPhaseOp` does not use this helper (its own fallback
+ * object differs by one field, `has_reviews` absent, so it is not a
+ * byte-identical copy), but since #4854 it resolves `roadmapPhase` once up
+ * front like the others, so `resolvePhaseDisplayName` sees it in the ordinary
+ * case too.
  *
  * Behavior-preserving by construction: every original call site either (a)
  * unconditionally computed `roadmapPhase` once up front and then applied
@@ -924,7 +945,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         // the human-curated display name (`### Phase N: <Name>`); prefer it,
         // matching the no-disk fallback above. phase_slug stays disk-derived — it
         // correctly feeds branch-name construction below and is unchanged here.
-        phase_name: (roadmapPhase?.['phase_name']) || (phaseInfo?.['phase_name']) || null,
+        phase_name: resolvePhaseDisplayName(phaseInfo, roadmapPhase),
         phase_slug: phaseInfo?.['phase_slug'] || null,
         phase_req_ids,
         plans: phaseInfo?.['plans'] || [],
@@ -1043,7 +1064,7 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     const phase_req_ids = reqExtracted && reqExtracted !== 'TBD' ? reqExtracted : null;
     const phaseDirPlan = phaseInfo?.['directory'] || null;
     const phaseNumberPlan = phaseInfo?.['phase_number'] || null;
-    const phaseNamePlan = phaseInfo?.['phase_name'] || null;
+    const phaseNamePlan = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const rawProjectCodePlan = config.project_code || '';
     let expectedPhaseDirPlan = null;
     if (!phaseDirPlan && phaseNumberPlan && phaseNamePlan) {
@@ -1689,7 +1710,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
         // itself stays relative — evaluateUatPassed above still joins it against cwd.
         phase_dir: phaseDir ? toPosixPath(node_path_1.default.join(cwd, phaseDir)) : null,
         phase_number: phaseInfo?.['phase_number'] || null,
-        phase_name: phaseInfo?.['phase_name'] || null,
+        phase_name: resolvePhaseDisplayName(phaseInfo, roadmapPhase),
         // #2376: verify-work.md's plan_gap_closure step reads these instead of
         // hardcoding '.planning/STATE.md' / '.planning/ROADMAP.md' literals.
         state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
@@ -1761,7 +1782,7 @@ function cmdInitCodeReview(cwd, phase, raw, options = {}) {
     });
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const fallow = detectFallowConfig(cwd);
     const result = {
         commit_docs: config.commit_docs,
@@ -1890,7 +1911,7 @@ function cmdInitDiscussPhaseAssumptions(cwd, phase, raw, options = {}) {
     });
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     // #2994: mirrors discuss-phase-assumptions.md's own auto_advance step
     // resolver — `--auto` flag OR the consolidated `check auto-mode --pick
     // active` fact (workflow._auto_chain_active OR workflow.auto_advance).
@@ -1942,8 +1963,10 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         output(withProjectRoot(cwd, result), raw);
         return;
     }
+    // #4854: resolved once, up front (a pure read — guardedGetRoadmapPhase has no side effects),
+    // so the ordinary case (phase dir on disk, not archived) also sees the ROADMAP display name.
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -1966,7 +1989,6 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -1990,7 +2012,7 @@ function cmdInitPhaseOp(cwd, phase, raw) {
     }
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const rawProjectCode = config.project_code || '';
     let expectedPhaseDir = null;
     if (!phaseDir && phaseNumber && phaseName) {
@@ -3753,7 +3775,7 @@ function buildAgentSkillsBlock(config, agentType, projectRoot, diagnostics) {
     }).join('\n');
     return `<agent_skills>\nRead these user-configured skills:\n${lines}\n</agent_skills>`;
 }
-function cmdAgentSkills(cwd, agentType, raw, jsonMode) {
+function cmdAgentSkills(cwd, agentType, raw, jsonMode, skillsOnly = false) {
     if (!agentType) {
         output('', raw, '');
         return;
@@ -3784,8 +3806,13 @@ function cmdAgentSkills(cwd, agentType, raw, jsonMode) {
     // (a real exit code) instead of a prose config-get gate. Compact is tried
     // first when requested; a missing compact sibling falls back to canonical
     // with the fallback disclosed in the payload itself, never a silent switch.
+    //
+    // #5122: `skillsOnly` (the CLI's `--skills-only`) is the agent's own
+    // self-load. It wants configured skills and nothing else, so it skips the
+    // fallback on every runtime — otherwise a non-Claude agent reads its own
+    // persona back into itself as if it were a skills block.
     let agentPayloadVariant = null;
-    if (!block) {
+    if (!block && !skillsOnly) {
         const runtime = (config && config['runtime']) || process.env['GSD_RUNTIME'] || 'claude';
         if (runtime !== 'claude') {
             const agentCheck = checkAgentsInstalled(runtime, projectRoot);
@@ -4051,7 +4078,7 @@ function buildSkillManifest(cwd, skillsDir = null) {
             if (!entry.isDirectory())
                 continue;
             const skillMdPath = node_path_1.default.join(rootPath, entry.name, 'SKILL.md');
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(skillMdPath);
+            const content = capabilityLedger.readSkillFile(skillMdPath);
             if (content !== null) {
                 if (pushSkillEntry(`${entry.name}/SKILL.md`, content, skillMdPath))
                     skillCount++;
@@ -4076,7 +4103,7 @@ function buildSkillManifest(cwd, skillsDir = null) {
                 if (!nested.isDirectory())
                     continue;
                 const nestedSkillMd = node_path_1.default.join(nestedSkillsDir, nested.name, 'SKILL.md');
-                const nestedContent = (0, shell_command_projection_cjs_1.platformReadSync)(nestedSkillMd);
+                const nestedContent = capabilityLedger.readSkillFile(nestedSkillMd);
                 if (nestedContent === null)
                     continue;
                 // Use forward-slash separator explicitly so manifest paths are posix-style

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

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  */
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_os_1 = __importDefault(require("node:os"));
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- install-fs-adapter.cjs is an export= CommonJS module
 const installFsAdapter = require("./install-fs-adapter.cjs");
 const { installFs } = installFsAdapter;
@@ -154,7 +154,7 @@ function _findAncestorGsdConfigPath(targetDir) {
  * @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');
+    const homeDefaults = _readGsdConfigFile(node_path_1.default.join((0, runtime_homes_cjs_1.resolveGsdHome)(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
     let projectConfig = null;
     if (targetDir) {
         const candidate = _findAncestorGsdConfigPath(targetDir);

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

@@ -1741,6 +1741,17 @@ function _installNativePluginIfDeclared(runtime, configDir, behaviors, src) {
             }
         }
     }
+    // OpenCode 2.x terminal-client plugin (ADR-5331 Phase 3): a TUI entrypoint kept in its own directory under
+    // plugins/. OpenCode 1.x scans plugins/*.js|ts only, so it never loads this directory.
+    const cli = behaviors.nativeCliPlugin;
+    if (cli && cli.source) {
+        const cliSrc = node_path_1.default.join(src, cli.source);
+        if (installFs().existsSync(cliSrc)) {
+            const cliDest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, node_path_1.default.join(cli.dir, cli.file));
+            installFs().mkdirSync(node_path_1.default.dirname(cliDest), { recursive: true });
+            installFs().copyFileSync(cliSrc, cliDest);
+        }
+    }
 }
 // ---------------------------------------------------------------------------
 // _migrateLegacyOpencodeCommandDir

package/gsd-core/bin/lib/install-model-override-resolver.cjs

@@ -34,6 +34,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  */
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- install-fs-adapter.cjs is an export= CommonJS module
 const installFsAdapter = require("./install-fs-adapter.cjs");
 const { installFs } = installFsAdapter;
@@ -57,7 +58,7 @@ const { resolveTierEntry: gsdResolveTierEntry, resolveModelPolicy: gsdResolveMod
  */
 function readGsdGlobalModelOverrides(options = {}) {
     try {
-        const home = options.homedir ? options.homedir() : node_os_1.default.homedir();
+        const home = (0, runtime_homes_cjs_1.resolveGsdHome)(options.homedir ? options.homedir() : node_os_1.default.homedir());
         const defaultsPath = node_path_1.default.join(home, '.gsd', 'defaults.json');
         if (!installFs().existsSync(defaultsPath))
             return null;
@@ -139,7 +140,7 @@ function readGsdAgentTools(config) {
  * model override resolver.
  */
 function readGsdEffectiveAgentTools(targetDir = null, options = {}) {
-    const home = options.homedir ? options.homedir() : node_os_1.default.homedir();
+    const home = (0, runtime_homes_cjs_1.resolveGsdHome)(options.homedir ? options.homedir() : node_os_1.default.homedir());
     const globalConfig = _readGsdConfigFile(node_path_1.default.join(home, '.gsd', 'defaults.json'), 'global defaults');
     let projectConfig = null;
     if (targetDir) {
@@ -170,7 +171,7 @@ function readGsdEffectiveAgentTools(targetDir = null, options = {}) {
  * baked, letting the runtime's own default/session model govern).
  */
 function readGsdRuntimeProfileResolver(targetDir = null) {
-    const homeDefaults = _readGsdConfigFile(node_path_1.default.join(node_os_1.default.homedir(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
+    const homeDefaults = _readGsdConfigFile(node_path_1.default.join((0, runtime_homes_cjs_1.resolveGsdHome)(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
     // #2875 defect fix (Generative Fix Divergence): same shared walk as
     // readGsdEffectiveModelOverrides above — see that call site's comment.
     let projectConfig = null;

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

@@ -31,6 +31,8 @@ const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // #2322: reuse the existing pure path-containment seam (ADR-1239 Phase C-2)
 // instead of hand-rolling a new traversal check for capability skill stems.
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- capability-ledger.cjs is an export= CommonJS module
+const capabilityLedger = require("./capability-ledger.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
 const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, } = conversionModule;
@@ -748,9 +750,9 @@ function readInstalledCapabilitySkill(stem, registry) {
         // installed as a capability skill (epic #4636).
         if (node_fs_1.default.lstatSync(skillPath).isSymbolicLink())
             return null;
-        if (!node_fs_1.default.statSync(skillPath).isFile())
-            return null;
-        return { capId, content: node_fs_1.default.readFileSync(skillPath, 'utf8') };
+        // #5121: the bounded regular-file read — a FIFO/device/oversized SKILL.md is skipped like a missing one.
+        const content = capabilityLedger.readSkillFile(skillPath);
+        return content === null ? null : { capId, content };
     }
     catch {
         return null; // missing / unreadable / corrupt entry -> skip

package/gsd-core/bin/lib/install-shadow-report.cjs

@@ -23,6 +23,10 @@
  * (design row #5 / "Not-corruption"). `kindsDiffer` on `ShadowReport` is what
  * lets `renderShadowReport` word the two cases correctly.
  *
+ * Same-scope pairs are not reported: a runtime whose layout installs `commands` and `skills` side by side at one
+ * scope (OpenCode, Kilo, Augment, CodeBuddy, ZCode) writes both on purpose, and `isGenuinelyShadowed` requires the
+ * winner and the loser to sit in different scopes (#5344).
+ *
  * ── Report, don't correct (mirrors the resolver's own law) ─────────────────
  * `mismatches` surfaces a declared runtime/scope that disagrees with the
  * probed one (Postel's Law, design doc: liberal in what is accepted, but the
@@ -218,6 +222,14 @@ function stemFromTrigger(trigger, prefix) {
 function isGenuinelyShadowed(t, scopeRecords, prefixFor) {
     if (t.shadowedBy === null)
         return false;
+    // This is a CROSS-SCOPE report (see the module comment). A winner and a loser in the SAME scope are the two
+    // kinds one install deliberately wrote side by side — OpenCode, Kilo, Augment, CodeBuddy and ZCode install
+    // `commands` and `skills` for every trigger at one scope. GSD wrote both, the operator cannot act on it, and
+    // the host's own dedupe (OpenCode 1.x lists the command and drops the same-named skill; 2.x keeps them on
+    // separate surfaces) is not a loss of reachability. Reporting it printed "72 triggers shadowed" on every
+    // install of those five runtimes (#5344).
+    if (t.shadowedBy.scope === t.scope)
+        return false;
     const winnerRecord = scopeRecords.get(t.shadowedBy.scope);
     const shadowedRecord = scopeRecords.get(t.scope);
     const winnerStem = stemFromTrigger(t.trigger, prefixFor(t.shadowedBy.scope, t.shadowedBy.kind));

package/gsd-core/bin/lib/installer-migrations/011-opencode-mcp-no-prompts.cjs

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Installer migration: stop the GSD MCP companion from duplicating every GSD command in OpenCode
+ * (#5338; epic #5331, ADR-5331 D6).
+ *
+ * OpenCode turns each MCP prompt into a `<server>:<prompt>` slash command. The GSD companion server
+ * advertised its whole prompt catalog, so with the command files the installer already writes every GSD
+ * command appeared twice (`gsd-plan-phase` and `gsd:plan-phase`; 143 entries against 72 observed on
+ * OpenCode 2.0.27). New installs register the server with `--no-prompts`. This migration converges an
+ * existing install by adding that flag to the `gsd` MCP entry GSD itself wrote — and only that entry: a
+ * `gsd` server the user edited or defined does not match the installer's shape and is never touched.
+ *
+ * It applies to OpenCode on both generations (the entry is the same shape), covers the 1.x `mcp.gsd` and
+ * the 2.x native `mcp.servers.gsd` locations, and edits the config as text so a commented `opencode.jsonc`
+ * keeps its comments and layout (#5334).
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. `rewrite-json` is non-interactive and journaled; the rewrite is a one-token append to a command
+ *   array the installer wrote.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and the OpenCode row of
+ * docs/installer-migrations.md#runtime-configuration-contract-registry.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const jsonc_edit_cjs_1 = require("../jsonc-edit.cjs");
+const opencode_mcp_entry_cjs_1 = require("../opencode-mcp-entry.cjs");
+/** OpenCode reads `opencode.jsonc` in preference to `opencode.json` when both exist. */
+const CONFIG_CANDIDATES = ['opencode.jsonc', 'opencode.json'];
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+const migration = {
+    id: '2026-10-12-opencode-mcp-no-prompts',
+    title: 'Stop the GSD MCP companion duplicating GSD commands in OpenCode',
+    description: 'Add --no-prompts to the GSD-written `gsd` MCP server entry in opencode.json(c) (mcp.gsd, and the ' +
+        'OpenCode 2.x native mcp.servers.gsd) so OpenCode no longer lists every GSD command a second time as ' +
+        'a `gsd:<name>` MCP-prompt command. Only the entry the installer wrote is changed; comments and ' +
+        'layout in a JSONC config are preserved (#5338, #5334).',
+    introducedIn: '1.17.0',
+    runtimes: ['opencode'],
+    scopes: ['global', 'local'],
+    destructive: false,
+    runtimeContract: 'docs/installer-migrations.md#runtime-configuration-contract-registry OpenCode row',
+    plan: (ctx) => {
+        if (ctx.runtime !== 'opencode')
+            return [];
+        // The file OpenCode (and the installer's resolveOpencodeConfigPath) treats as THE config.
+        const relPath = CONFIG_CANDIDATES.find((name) => node_fs_1.default.existsSync(node_path_1.default.join(ctx.configDir, name)));
+        if (!relPath)
+            return [];
+        let config;
+        try {
+            config = (0, jsonc_edit_cjs_1.parseJsonc)(node_fs_1.default.readFileSync(node_path_1.default.join(ctx.configDir, relPath), 'utf8'));
+        }
+        catch {
+            return []; // unparseable: never touch a config we cannot read (same posture as the installer)
+        }
+        if (!isPlainObject(config) || !isPlainObject(config['mcp']))
+            return [];
+        const mcp = config['mcp'];
+        const edits = [];
+        const next = { ...config, mcp: { ...mcp } };
+        const nextMcp = next['mcp'];
+        const legacy = mcp['gsd'];
+        if ((0, opencode_mcp_entry_cjs_1.isGsdMcpEntry)(legacy) && !(0, opencode_mcp_entry_cjs_1.hasNoPromptsFlag)(legacy)) {
+            const updated = (0, opencode_mcp_entry_cjs_1.withNoPromptsFlag)(legacy);
+            nextMcp['gsd'] = updated;
+            edits.push({ path: ['mcp', 'gsd', 'command'], value: updated.command });
+        }
+        const servers = mcp['servers'];
+        if (isPlainObject(servers)) {
+            const native = servers['gsd'];
+            if ((0, opencode_mcp_entry_cjs_1.isGsdMcpEntry)(native) && !(0, opencode_mcp_entry_cjs_1.hasNoPromptsFlag)(native)) {
+                const updated = (0, opencode_mcp_entry_cjs_1.withNoPromptsFlag)(native);
+                nextMcp['servers'] = { ...servers, gsd: updated };
+                edits.push({ path: ['mcp', 'servers', 'gsd', 'command'], value: updated.command });
+            }
+        }
+        if (edits.length === 0)
+            return [];
+        return [
+            {
+                type: 'rewrite-json',
+                relPath,
+                value: next,
+                edits,
+                reason: 'the GSD MCP companion advertised its prompt catalog, which OpenCode lists as a second set of ' +
+                    '`gsd:<name>` slash commands next to the installed command files',
+                ownershipEvidence: "the entry matches the exact shape configureOpencodePermissions writes: type 'local' and a command " +
+                    "array of `npx … <package> gsd-mcp-server`; a user-edited or user-defined `gsd` server does not match",
+            },
+        ];
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -18,6 +18,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const clock_cjs_1 = require("./clock.cjs");
 const install_scope_cjs_1 = require("./install-scope.cjs");
 const security_cjs_1 = require("./security.cjs");
+const jsonc_edit_cjs_1 = require("./jsonc-edit.cjs");
 // #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
 // plan/apply/rollback/lock/journal engine — almost none of it is on the
 // installRuntimeArtifacts call tree. Only `readInstallManifest` and
@@ -293,15 +294,25 @@ function readInstallManifest(configDir) {
         scope: (0, install_scope_cjs_1.isInstallScopeId)(m.scope) ? m.scope : null,
     };
 }
+function normalizeHostGeneration(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (r.runtime !== 'opencode' || (r.generation !== 1 && r.generation !== 2))
+        return undefined;
+    return { runtime: 'opencode', generation: r.generation, version: typeof r.version === 'string' ? r.version : null };
+}
 function readInstallState(configDir) {
     const state = readJsonIfPresent(node_path_1.default.join(configDir, INSTALL_STATE_NAME), STRICT_JSON);
     if (!state || typeof state !== 'object') {
         return { schemaVersion: 1, appliedMigrations: [] };
     }
     const s = state;
+    const hostGeneration = normalizeHostGeneration(s.hostGeneration);
     return {
         schemaVersion: typeof s.schemaVersion === 'number' ? s.schemaVersion : 1,
         appliedMigrations: Array.isArray(s.appliedMigrations) ? s.appliedMigrations : [],
+        ...(hostGeneration ? { hostGeneration } : {}),
     };
 }
 // Strict atomic write for the install state: must never be left half-written.
@@ -654,6 +665,31 @@ function journalAction(action, status, extras = {}) {
     const { value: _value, ...safeAction } = action;
     return { ...safeAction, ...extras, status };
 }
+/**
+ * The text a `rewrite-json` action writes. A file with JSONC syntax (comments, trailing commas, or a
+ * `.jsonc` name) is edited in place from the action's `edits`, so the user's annotations survive (#5334);
+ * everything else, and any edit the text editor cannot place, is written as the action's whole `value`.
+ */
+function renderRewrittenJson(fullPath, action) {
+    if (Array.isArray(action.edits) && action.edits.length > 0) {
+        let original = null;
+        try {
+            original = node_fs_1.default.readFileSync(fullPath, 'utf8');
+        }
+        catch { /* fall through to the value rewrite */ }
+        if (original !== null && (fullPath.endsWith('.jsonc') || (0, jsonc_edit_cjs_1.hasJsoncFeatures)(original))) {
+            let text = original;
+            for (const edit of action.edits) {
+                text = (0, jsonc_edit_cjs_1.setJsoncValue)(text, edit.path, edit.value);
+                if (text === null)
+                    break;
+            }
+            if (text !== null)
+                return text;
+        }
+    }
+    return JSON.stringify(action.value, null, 2) + '\n';
+}
 function planInstallerMigrations({ configDir, runtime = null, scope = null, migrations, baselineScan = false, now = () => new Date().toISOString(), }) {
     if (!configDir)
         throw new Error('configDir is required');
@@ -725,6 +761,8 @@ function planInstallerMigrations({ configDir, runtime = null, scope = null, migr
             }
             if (action.type === 'rewrite-json') {
                 action.value = rawAction.value;
+                if (Array.isArray(rawAction.edits))
+                    action.edits = rawAction.edits;
                 action.deleteIfEmpty = rawAction.deleteIfEmpty === true;
             }
             if (rawAction.prompt)
@@ -896,7 +934,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                     }));
                 }
                 else {
-                    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, JSON.stringify(action.value, null, 2) + '\n');
+                    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, renderRewrittenJson(fullPath, action));
                     journal.actions.push(journalAction(action, 'rewritten', {
                         rollbackRelPath: node_path_1.default.posix.join(rollbackRootRelPath, normalized),
                     }));
@@ -945,6 +983,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
         writeInstallState(configDir, {
             schemaVersion: 1,
             appliedMigrations: nextApplied,
+            ...(state.hostGeneration ? { hostGeneration: state.hostGeneration } : {}),
         });
         return {
             appliedMigrationIds: journal.appliedMigrationIds,
@@ -1017,6 +1056,7 @@ function markPendingMigrationsApplied({ configDir, plan, now = () => new Date().
         writeInstallState(configDir, {
             schemaVersion: 1,
             appliedMigrations: nextApplied,
+            ...(state.hostGeneration ? { hostGeneration: state.hostGeneration } : {}),
         });
     }
     return newlyApplied;
@@ -1073,6 +1113,18 @@ function runInstallerMigrations({ configDir, runtime = null, scope = null, migra
 // Unused but kept to satisfy eslint — sleepSync is referenced in the original
 // and may be used by test code that patches this module.
 void sleepSync;
+/**
+ * Record which OpenCode generation this install targets (ADR-5331 D2; #5337). Idempotent and
+ * atomic; leaves the applied-migrations journal untouched.
+ */
+function recordHostGeneration(configDir, info) {
+    const state = readInstallState(configDir);
+    const next = { runtime: 'opencode', generation: info.generation, version: info.version ?? null };
+    const prev = state.hostGeneration;
+    if (prev && prev.generation === next.generation && prev.version === next.version)
+        return;
+    writeInstallState(configDir, { ...state, hostGeneration: next });
+}
 module.exports = {
     DEFAULT_MIGRATIONS_DIR,
     INSTALL_MIGRATION_LOCK_NAME,
@@ -1089,6 +1141,7 @@ module.exports = {
     planInstallerMigrations,
     readInstallManifest,
     readInstallState,
+    recordHostGeneration,
     runInstallerMigrations,
     writeInstallState,
 };