@opengsd/gsd-core 1.15.0 → 1.17.0

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

@@ -55,7 +55,7 @@ const install_scope_cjs_1 = require("./install-scope.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.
-const { getDirName } = runtimeNamePolicy;
+const { getDirName, hostBehaviorsFor } = runtimeNamePolicy;
 function withInstallerPackageSource(configDir, fn) {
     // Reuse the existing compatibility-marker contract through the existing fs
     // seam. The marker exists only in this synchronous call tree: no disk state,
@@ -181,7 +181,7 @@ function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
         const destination = node_path_1.default.join(corpusRoot, 'agents');
         syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/agents/');
     }
-    const markerFile = _hostBehaviors(layout.runtime).sourceMarkerFile;
+    const markerFile = hostBehaviorsFor(layout.runtime).sourceMarkerFile;
     if (typeof markerFile === 'string' && markerFile !== '' && required.has('commands')) {
         try {
             const markerPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, markerFile);
@@ -220,25 +220,6 @@ function executingPackageRoot() { return node_path_1.default.dirname(node_path_1
  */
 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
 // ---------------------------------------------------------------------------
 /**
@@ -737,8 +718,9 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
         // files whose `name:` frontmatter is identical to their canonical
         // sibling's, leaving the harness resolution unstated. Claude never
         // selects compact, so claude is the one runtime whose agents kind skips
-        // them; every other runtime's emission is byte-identical.
-        if (kind.kind === 'agents' && runtime === 'claude' && entry.name.endsWith('.compact.md'))
+        // them; every other runtime's emission is byte-identical. #5169: the
+        // descriptor declares this (`hostBehaviors.skipCompactAgents`), not a name test.
+        if (kind.kind === 'agents' && hostBehaviorsFor(runtime).skipCompactAgents && entry.name.endsWith('.compact.md'))
             continue;
         const stem = entry.name.slice(0, -3); // strip .md
         let destName;
@@ -748,7 +730,7 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
             // hardcoded `runtime === 'copilot'`). copilot declares '.agent.md';
             // every other runtime's descriptor leaves this unset, so destName falls
             // back to entry.name unchanged (byte-parity, #1575 origin comment).
-            const _agentExt = runtime ? _hostBehaviors(runtime).agentFileExtension : undefined;
+            const _agentExt = runtime ? hostBehaviorsFor(runtime).agentFileExtension : undefined;
             destName = _agentExt
                 ? entry.name.replace(/\.md$/, _agentExt)
                 : entry.name;
@@ -887,7 +869,7 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
     // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
     // created skills/gsd-dev-preferences/ skill dir.
     let stagedLegacyArtifacts = null;
-    if (_hostBehaviors(runtime).legacyCommandsGsdInstallMigration) {
+    if (hostBehaviorsFor(runtime).legacyCommandsGsdInstallMigration) {
         if (installFs().existsSync(legacyCommandsGsd)) {
             // #2875: staging root resolved lazily, only when there is actually
             // something to stage — reused below by every other call site sharing
@@ -911,8 +893,8 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
         }
     }
     // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
-    // the new skills/gsd/ nested layout.
-    if (runtime === 'hermes') {
+    // the new skills/gsd/ nested layout. (#5169: `hostBehaviors.legacyFlatSkillsCleanup`.)
+    if (hostBehaviorsFor(runtime).legacyFlatSkillsCleanup) {
         const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
         if (installFs().existsSync(flatSkillsDir)) {
             for (const entry of installFs().readdirSync(flatSkillsDir, { withFileTypes: true })) {
@@ -1050,7 +1032,7 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
     // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
     // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
     // (which would redirect to skills/) conflicts with the test contract for local installs.
-    const _lu = _hostBehaviors(runtime).legacyCommandsGsdUninstall;
+    const _lu = hostBehaviorsFor(runtime).legacyCommandsGsdUninstall;
     // #2870: `scope` keeps its exported `string = 'global'` signature (no
     // signature change), but every real caller — `uninstallRuntimeArtifacts`'s
     // own required `scope` param, always fed a validated 'global' | 'local'
@@ -1075,8 +1057,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
             }
         }
     }
-    // Hermes: pre-#2841 flat skills/gsd-*/ entries
-    if (runtime === 'hermes') {
+    // Hermes: pre-#2841 flat skills/gsd-*/ entries (#5169: `legacyFlatSkillsCleanup`)
+    if (hostBehaviorsFor(runtime).legacyFlatSkillsCleanup) {
         const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
         if (node_fs_1.default.existsSync(flatSkillsDir)) {
             for (const entry of node_fs_1.default.readdirSync(flatSkillsDir, { withFileTypes: true })) {
@@ -1085,6 +1067,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
                 }
             }
         }
+    }
+    if (hostBehaviorsFor(runtime).bareStemSkillsCleanup) {
         // Hermes: pre-#947 bare-stem skills/gsd/<stem>/ entries (dirs that do NOT
         // start with 'gsd-') — the #3664 layout used prefix='' so GSD-owned skills
         // had bare names (e.g. skills/gsd/help/). These are stale on uninstall.
@@ -1142,7 +1126,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // 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);
+        const behaviors = hostBehaviorsFor(runtime);
         const projectDir = scope === 'global' ? process.cwd() : configDir;
         if (behaviors.combinedFamilyInstall) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
@@ -1336,7 +1320,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // with the same prefix). User-owned bare dirs with no gsd-<stem> counterpart
         // are untouched.
         let hermesBareStemCleanup = false;
-        if (runtime === 'hermes') {
+        if (hostBehaviorsFor(runtime).bareStemSkillsCleanup) {
             const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
             _removeHermesBareStemDirs(nestedGsdDirForCleanup);
             hermesBareStemCleanup = true;
@@ -1688,7 +1672,7 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
             // already satisfies the fold-to-descriptor requirement. Only the SKILLS
             // converter site above (installOpencodeFamilySkills) has a real
             // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
-            content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
+            content = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
                 ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
                 : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
             installFs().writeFileSync(node_path_1.default.join(destDir, destName), content);
@@ -1757,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
@@ -1971,7 +1966,8 @@ function uninstallRuntimeArtifacts(runtime, configDir, scope, deps = {}) {
     // the GSD-managed DESCRIPTION.md and then the category dir itself if it
     // contains no user content (#947). _removeGsdEntries removed gsd-* dirs
     // but left the category container and DESCRIPTION.md intact.
-    if (runtime === 'hermes') {
+    // (#5169: `hostBehaviors.categoryContainerCleanup`.)
+    if (hostBehaviorsFor(runtime).categoryContainerCleanup) {
         const nestedGsdDir = node_path_1.default.join(configDir, 'skills', 'gsd');
         if (node_fs_1.default.existsSync(nestedGsdDir)) {
             // Remove GSD-owned DESCRIPTION.md (written by writeHermesCategoryDescription)
@@ -2029,7 +2025,6 @@ module.exports = {
     installAgentsKindStandalone,
     installOpencodeFamilyArtifacts,
     _installNativePluginIfDeclared,
-    _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,
     isSymlinkedDestOptIn,

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

@@ -27,6 +27,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const installFsAdapter = require("./install-fs-adapter.cjs");
 const { installFs, mkInstallTempDir } = installFsAdapter;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+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");
@@ -95,13 +96,15 @@ const PROFILES = Object.freeze({
  * Returns string[] — empty array if no requires: field.
  *
  * No external YAML parser dependency — hand-parse the single line
- * since GSD enforces flow-style arrays for requires:.
+ * since GSD enforces flow-style arrays for requires:. The block is the one the
+ * one fence owner (`locateFrontmatterFence`) finds — a `---` pair later in the
+ * body (a thematic break, a YAML example) is never frontmatter.
  */
 function parseRequires(content) {
-    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/m);
-    if (!fmMatch)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return [];
-    const fm = fmMatch[1];
+    const fm = content.slice(fence.openEnd, fence.bodyEnd);
     const line = fm.match(/^requires:\s*(.+)$/m);
     if (!line)
         return [];

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,
 };

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

@@ -121,6 +121,84 @@ function writeAllSync(fd, data) {
         }
     }
 }
+/**
+ * Temporarily patch `fs.writeSync` so everything written to fd 1 (stdout) is
+ * captured into a string instead of reaching the real stdout, run `run`, then
+ * restore the original `fs.writeSync` and resolve with what was captured.
+ *
+ * The ONE shared helper (#5105 S9) for "run a nested command and read its own
+ * JSON envelope back as data instead of letting it reach the real stdout" —
+ * used by gsd-tools.cjs's `--pick`/`@file:` resolution and by `uat.cts`'s
+ * `cmdUatCompleteSession` (which needs `cmdCommit`'s result object without
+ * emitting cmdCommit's own envelope as a second line of output). A single
+ * definition means both callers see the same Buffer/string/encoding handling
+ * and the same throw-mid-write flush behavior, rather than two hand-rolled
+ * monkeypatches drifting apart.
+ *
+ * On a throw from `run`, whatever was captured before the throw is flushed to
+ * the REAL stdout — the wrapped command may have already written its own
+ * JSON envelope and THEN thrown to set a non-zero exit code (e.g. a
+ * capability set/disable on an unknown id); without this flush that output
+ * would be silently discarded, since the success-path flush at the call site
+ * never runs on a throw. The error still propagates so the exit code is
+ * preserved.
+ */
+function captureStdoutSyncWrites(run) {
+    const originalWriteSync = node_fs_1.default.writeSync;
+    let captured = '';
+    node_fs_1.default.writeSync = ((fd, data, ...rest) => {
+        if (fd === 1) {
+            if (Buffer.isBuffer(data)) {
+                captured += data.toString('utf-8');
+                return data.length;
+            }
+            const text = String(data);
+            captured += text;
+            let encoding = 'utf-8';
+            if (typeof rest[1] === 'string')
+                encoding = rest[1];
+            return Buffer.byteLength(text, encoding);
+        }
+        return originalWriteSync.call(node_fs_1.default, fd, data, ...rest);
+    });
+    const restore = () => {
+        node_fs_1.default.writeSync = originalWriteSync;
+    };
+    return Promise.resolve()
+        .then(() => run())
+        .then(() => {
+        restore();
+        return captured;
+    }, (err) => {
+        restore();
+        if (captured) {
+            try {
+                originalWriteSync.call(node_fs_1.default, 1, captured);
+            }
+            catch { /* best-effort flush */ }
+        }
+        throw err;
+    });
+}
+/**
+ * Resolve `output()`'s `@file:<path>` redirection (emitted for a >50KB JSON
+ * payload) back to the real content, or return `captured` unchanged when it
+ * is not that shape.
+ *
+ * #5105 review finding 7: the ONE definition, shared by gsd-tools.cjs's
+ * `--pick`/CLI-passthrough resolution and by `uat.cts`'s
+ * `cmdUatCompleteSession` (which reads `cmdCommit`'s captured result back
+ * without emitting cmdCommit's own envelope as a second stdout line) — same
+ * reasoning as `captureStdoutSyncWrites` just below: one definition means
+ * both callers agree on the trailing-newline-free prefix and the read
+ * encoding, rather than two hand-rolled `startsWith('@file:')` checks
+ * drifting apart.
+ */
+function resolveAtFileOutput(captured) {
+    if (!captured.startsWith('@file:'))
+        return captured;
+    return node_fs_1.default.readFileSync(captured.slice('@file:'.length), 'utf-8');
+}
 /**
  * The wire form of a JSON result: the exact bytes `output()` emits for it.
  *
@@ -290,6 +368,16 @@ const ERROR_REASON = Object.freeze({
     // exit 0. See .gsd/phase/feat-3884-failure-is-a-value/40-design.md.
     PICK_FIELD_ABSENT: 'pick_field_absent',
     PICK_OUTPUT_NOT_JSON: 'pick_output_not_json',
+    // summary-extract (#5013): the SUMMARY's frontmatter fence exists but failed
+    // to parse (extractFrontmatter's FRONTMATTER_UNPARSEABLE marker) — a
+    // distinct failure from "no frontmatter"/"field absent", never a silent
+    // demotion to empty fields at exit 0.
+    SUMMARY_EXTRACT_UNPARSEABLE: 'summary_extract_unparseable',
+    // verification (#5118, ADR-5057 Phase 4): a *-VERIFICATION.md frontmatter
+    // `status` outside the closed writer set (`passed | gaps_found |
+    // human_needed`) — verification.cts's VerificationStatusError, translated
+    // once, centrally, by gsd-tools.cjs. Never read as "no result" at exit 0.
+    VERIFICATION_STATUS_INVALID: 'verification_status_invalid',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',
@@ -334,14 +422,35 @@ const ERROR_REASON = Object.freeze({
  * more than one line or introduce an unescaped `"`. Callers embedding the
  * result MUST NOT add their own surrounding quotes — that would
  * double-quote it.
+ *
+ * #5118 security review: `JSON.stringify` leaves characters that render
+ * invisibly or reorder the text around them untouched — DEL and the C1
+ * controls (U+007F–U+009F), the line/paragraph separators (U+2028–U+2029),
+ * zero-width and directional marks (U+200B–U+200F), the bidi embeddings and
+ * overrides (U+202A–U+202E), the bidi isolates (U+2066–U+2069) and the BOM
+ * (U+FEFF). Each is escaped as `\uXXXX` so the token reads exactly as its
+ * code points are, whoever renders it.
  */
+const INVISIBLE_OR_BIDI_RANGES = [
+    [0x7f, 0x9f],
+    [0x2028, 0x2029],
+    [0x200b, 0x200f],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+];
+/** Code points as `\uXXXX` escape text (source stays ASCII; no literal invisible characters). */
+function toUnicodeEscape(codePoint) {
+    return `\\u${codePoint.toString(16).padStart(4, '0')}`;
+}
+const INVISIBLE_OR_BIDI_RE = new RegExp(`[${INVISIBLE_OR_BIDI_RANGES.map(([lo, hi]) => `${toUnicodeEscape(lo)}-${toUnicodeEscape(hi)}`).join('')}]`, 'g');
 function formatDiagnosticToken(value) {
-    return JSON.stringify(value);
+    return JSON.stringify(value).replace(INVISIBLE_OR_BIDI_RE, (ch) => toUnicodeEscape(ch.charCodeAt(0)));
 }
 /**
  * Map an ERROR_REASON wire value onto a declared outcome name (#3912,
- * ADR-3889 §4). Closed over the 25-member enum: every reason gets an
- * explicit entry below, so a 26th member added without a mapping falls
+ * ADR-3889 §4). Closed over the 27-member enum: every reason gets an
+ * explicit entry below, so a 28th member added without a mapping falls
  * through to the `?? 'FAIL'` default rather than silently mis-projecting —
  * and tests/A1 iterates `Object.values(ERROR_REASON)`, so that default is
  * exactly what makes an unmapped addition visible instead of invisible.
@@ -389,6 +498,14 @@ const REASON_TO_OUTCOME = Object.freeze({
     // supposed to be there and was not; a prerequisite of the query failed.
     [ERROR_REASON.PICK_FIELD_ABSENT]: 'UNAVAILABLE',
     [ERROR_REASON.PICK_OUTPUT_NOT_JSON]: 'UNAVAILABLE',
+    // #5013: the SUMMARY's frontmatter fence exists but failed to parse — the
+    // prerequisite of the query (readable frontmatter) is what's broken, same
+    // shape as PICK_FIELD_ABSENT/PICK_OUTPUT_NOT_JSON just above.
+    [ERROR_REASON.SUMMARY_EXTRACT_UNPARSEABLE]: 'UNAVAILABLE',
+    // #5118: the verification report exists but its `status` is not a verdict
+    // the reader accepts — a broken prerequisite of the query, the same shape
+    // as SUMMARY_EXTRACT_UNPARSEABLE just above.
+    [ERROR_REASON.VERIFICATION_STATUS_INVALID]: 'UNAVAILABLE',
     // Self-failure: the run itself broke, not its inputs.
     [ERROR_REASON.SDK_FAIL_FAST]: 'INTERNAL',
     [ERROR_REASON.SECURITY_SCAN_FAILED]: 'INTERNAL',
@@ -433,4 +550,6 @@ module.exports = {
     getJsonErrorMode,
     error,
     formatDiagnosticToken,
+    captureStdoutSyncWrites,
+    resolveAtFileOutput,
 };