@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/capability-source.cjs

@@ -153,16 +153,31 @@ function _setCapabilitySourceHttpGet(fn) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Resolve the running GSD version; fail-closed to '0.0.0'. */
-function readHostVersion() {
+/**
+ * Resolve the running GSD version; fail-closed to '0.0.0'.
+ *
+ * Prefer the authoritative `gsd-core/VERSION` the installer writes for EVERY runtime
+ * (libDir = gsd-core/bin/lib/, so `../../VERSION` = gsd-core/VERSION), so installed
+ * layouts report the true version even when the walked-up `../../../package.json` is
+ * absent or belongs to the user's own project (#1920). Fall back to the runtime-root
+ * package.json (dev/source tree), then fail-closed. Mirrors resolveVersionFrom() (#1383).
+ */
+function readHostVersion(libDir = __dirname) {
+    const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const pkg = require('../../../package.json');
-        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+        const v = node_fs_1.default.readFileSync(node_path_1.default.join(libDir, '..', '..', 'VERSION'), 'utf8').trim();
+        if (SEMVER_PREFIX.test(v))
+            return v;
     }
-    catch {
-        return '0.0.0';
+    catch { /* not an installed tree (no gsd-core/VERSION) */ }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pkg = require(node_path_1.default.join(libDir, '..', '..', '..', 'package.json'));
+        if (pkg && typeof pkg.version === 'string' && SEMVER_PREFIX.test(pkg.version))
+            return pkg.version;
     }
+    catch { /* runtime root has no package.json */ }
+    return '0.0.0';
 }
 /** Compute sha512-<base64> integrity over a buffer. */
 function computeIntegrity(buf) {
@@ -594,13 +609,13 @@ function stageValidated(opts) {
         // lives in capability-lifecycle.cjs and uses promote:false above.)
         if (node_fs_1.default.existsSync(finalDir)) {
             const backupDir = `${finalDir}.old-${process.pid}-${Date.now()}`;
-            node_fs_1.default.renameSync(finalDir, backupDir);
+            shellSeam.retryRenameSync(finalDir, backupDir);
             try {
-                node_fs_1.default.renameSync(stagingDir, finalDir);
+                shellSeam.retryRenameSync(stagingDir, finalDir);
             }
             catch (err) {
                 try {
-                    node_fs_1.default.renameSync(backupDir, finalDir);
+                    shellSeam.retryRenameSync(backupDir, finalDir);
                 }
                 catch { /* best-effort restore */ }
                 throw err;
@@ -611,7 +626,7 @@ function stageValidated(opts) {
             catch { /* best-effort */ }
         }
         else {
-            node_fs_1.default.renameSync(stagingDir, finalDir);
+            shellSeam.retryRenameSync(stagingDir, finalDir);
         }
         const version = typeof cap['version'] === 'string' ? cap['version'] : '';
         return { id, version, stagedDir: finalDir, integrity, source };

package/gsd-core/bin/lib/capability-validator.cjs

@@ -704,7 +704,12 @@ const VALID_CONFIG_FORMATS = new Set(['settings-json', 'toml', 'markdown', 'mark
 const VALID_CONFIG_HOME_KINDS = new Set(['dot-home', 'dot-home-nested', 'xdg', 'generic-agents-root']);
 const VALID_COMMAND_STYLES = new Set(['slash-hyphen', 'shell-var']);
 const VALID_HOOKS_SURFACES = new Set(['settings-json', 'codex-hooks-json', 'cursor-hooks-json', 'copilot-inline', 'cline-rules', 'none']);
-const VALID_HOOK_EVENTS = new Set(['claude', 'gemini', 'opencode-subset']);
+const VALID_HOOK_EVENTS = new Set(['claude', 'gemini']);
+// extensionEvents — the plugin/extension-system event dialect (ADR-1239 amendment / #1943).
+// DISTINCT from hookEvents (managed-hook dialect): extensionEvents describes the
+// plugin-owned event subset imperative hosts expose (opencode / pi); 'none' = the
+// host exposes no extension surface (engine owns the bus, e.g. VS Code).
+const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'none']);
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 const VALID_ARTIFACT_KIND_NAMES = new Set(['commands', 'agents', 'skills', 'kimi-agents']);
 const VALID_ARTIFACT_NESTINGS = new Set(['flat', 'nested']);
@@ -713,6 +718,16 @@ const VALID_INSTALL_SURFACES = new Set(['settings-json', 'codex-toml', 'copilot-
 const VALID_PERMISSION_WRITERS = new Set(['opencode', 'kilo']);
 const VALID_EXTENDED_HOOK_EVENTS = new Set(['SubagentStop', 'Stop', 'PreCompact', 'FileChanged', 'BeforeAgent', 'AfterAgent', 'BeforeModel']);
 
+// ADR-1239 Phase A: hostIntegration axes (MUST stay parity-identical to HOST_INTEGRATION_AXES in src/host-integration.cts)
+const VALID_EMBEDDING_MODES   = new Set(['imperative', 'declarative']);
+const VALID_COMMAND_SURFACES  = new Set(['slash-file', 'slash-programmatic', 'slash-toml', 'palette', 'prose-only']);
+const VALID_MODEL_MODES       = new Set(['active', 'passive']);
+const VALID_HOOK_BUSES        = new Set(['host', 'engine', 'none']);
+const VALID_STATE_IO          = new Set(['filesystem', 'sandboxed-storage', 'session-log-append']);
+const VALID_TRANSPORTS        = new Set(['mcp', 'native-extension']);
+const VALID_HOST_RUNTIMES     = new Set(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']);
+const VALID_SUBAGENT_TOOLKITS = new Set(['full', 'read-only']);
+
 // GATE A: installSurface → allowed hooksSurface values (DEFECT.GENERATIVE-FIX: parity invariant)
 // Derived from the actual pairings in the 16 real runtime descriptors.
 const INSTALL_SURFACE_TO_ALLOWED_HOOKS_SURFACES = new Map([
@@ -968,7 +983,9 @@ function validateRuntimeBody(cap) {
     );
   }
 
-  // hookEvents — optional; if present must be in closed 3-enum (ADR-1016 Decision 5)
+  // hookEvents — optional; if present must be in closed enum (ADR-1016 Decision 5).
+  // Managed-hook dialect only (claude/gemini). The OpenCode extension-system event
+  // subset is NOT a hookEvents value — it is `extensionEvents` (ADR-1239 / #1943).
   if (r.hookEvents !== undefined) {
     if (r.hookEvents === '__proto__' || r.hookEvents === 'constructor' || r.hookEvents === 'prototype') {
       errors.push('runtime.hookEvents "' + r.hookEvents + '" is a reserved name');
@@ -980,6 +997,20 @@ function validateRuntimeBody(cap) {
     }
   }
 
+  // extensionEvents — optional; the extension-system event dialect (ADR-1239 amendment / #1943).
+  // Distinct from hookEvents. Only imperative-embedding hosts (with a plugin/extension
+  // API) set it; declarative hosts do not.
+  if (r.extensionEvents !== undefined) {
+    if (r.extensionEvents === '__proto__' || r.extensionEvents === 'constructor' || r.extensionEvents === 'prototype') {
+      errors.push('runtime.extensionEvents "' + r.extensionEvents + '" is a reserved name');
+    } else if (!VALID_EXTENSION_EVENTS.has(r.extensionEvents)) {
+      errors.push(
+        'runtime.extensionEvents must be one of: ' + [...VALID_EXTENSION_EVENTS].join(', ') +
+        ' (got: ' + JSON.stringify(r.extensionEvents) + ')',
+      );
+    }
+  }
+
   // sandboxTier — closed 2-enum (ADR-1016 Decision 6); inline literal guard (CodeQL barrier)
   if (r.sandboxTier === '__proto__' || r.sandboxTier === 'constructor' || r.sandboxTier === 'prototype') {
     errors.push('runtime.sandboxTier "' + r.sandboxTier + '" is a reserved name');
@@ -1020,6 +1051,20 @@ function validateRuntimeBody(cap) {
     );
   }
 
+  // localConfigDir — REQUIRED non-empty dot-dir string (ADR-1239 Phase B #1679)
+  // Must start with '.' (e.g. ".claude", ".cursor"). Validated here so the registry
+  // generator catches any descriptor missing the field before regenerating.
+  if (typeof r.localConfigDir !== 'string' || r.localConfigDir.length === 0) {
+    errors.push(
+      'runtime.localConfigDir is required and must be a non-empty string (e.g. ".claude"); ' +
+      'got: ' + JSON.stringify(r.localConfigDir),
+    );
+  } else if (!r.localConfigDir.startsWith('.')) {
+    errors.push(
+      'runtime.localConfigDir must start with "." (a dot-dir); got: ' + JSON.stringify(r.localConfigDir),
+    );
+  }
+
   // extendedHookEvents — required array; every element must be in closed enum
   if (!Array.isArray(r.extendedHookEvents)) {
     errors.push(
@@ -1037,6 +1082,162 @@ function validateRuntimeBody(cap) {
     }
   }
 
+  // hostIntegration — ADR-1239 Phase A: required object with closed-enum axes
+  if (typeof r.hostIntegration !== 'object' || r.hostIntegration === null || Array.isArray(r.hostIntegration)) {
+    errors.push('runtime.hostIntegration is required and must be an object');
+  } else {
+    const hi = r.hostIntegration;
+
+    // S2b: reserved-OWN-KEY guard on hostIntegration (CodeQL barrier — inline literal comparisons)
+    if (Object.prototype.hasOwnProperty.call(hi, '__proto__')) {
+      errors.push('runtime.hostIntegration must not contain reserved key "__proto__"');
+    }
+    if (Object.prototype.hasOwnProperty.call(hi, 'constructor')) {
+      errors.push('runtime.hostIntegration must not contain reserved key "constructor"');
+    }
+    if (Object.prototype.hasOwnProperty.call(hi, 'prototype')) {
+      errors.push('runtime.hostIntegration must not contain reserved key "prototype"');
+    }
+
+    // embeddingMode
+    if (hi.embeddingMode === '__proto__' || hi.embeddingMode === 'constructor' || hi.embeddingMode === 'prototype') {
+      errors.push('runtime.hostIntegration.embeddingMode "' + hi.embeddingMode + '" is a reserved name');
+    } else if (hi.embeddingMode !== 'undocumented' && !VALID_EMBEDDING_MODES.has(hi.embeddingMode)) {
+      errors.push(
+        'runtime.hostIntegration.embeddingMode must be one of: ' + [...VALID_EMBEDDING_MODES].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.embeddingMode) + ')',
+      );
+    }
+
+    // commandSurface
+    if (hi.commandSurface === '__proto__' || hi.commandSurface === 'constructor' || hi.commandSurface === 'prototype') {
+      errors.push('runtime.hostIntegration.commandSurface "' + hi.commandSurface + '" is a reserved name');
+    } else if (hi.commandSurface !== 'undocumented' && !VALID_COMMAND_SURFACES.has(hi.commandSurface)) {
+      errors.push(
+        'runtime.hostIntegration.commandSurface must be one of: ' + [...VALID_COMMAND_SURFACES].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.commandSurface) + ')',
+      );
+    }
+
+    // modelMode
+    if (hi.modelMode === '__proto__' || hi.modelMode === 'constructor' || hi.modelMode === 'prototype') {
+      errors.push('runtime.hostIntegration.modelMode "' + hi.modelMode + '" is a reserved name');
+    } else if (hi.modelMode !== 'undocumented' && !VALID_MODEL_MODES.has(hi.modelMode)) {
+      errors.push(
+        'runtime.hostIntegration.modelMode must be one of: ' + [...VALID_MODEL_MODES].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.modelMode) + ')',
+      );
+    }
+
+    // hookBus
+    if (hi.hookBus === '__proto__' || hi.hookBus === 'constructor' || hi.hookBus === 'prototype') {
+      errors.push('runtime.hostIntegration.hookBus "' + hi.hookBus + '" is a reserved name');
+    } else if (hi.hookBus !== 'undocumented' && !VALID_HOOK_BUSES.has(hi.hookBus)) {
+      errors.push(
+        'runtime.hostIntegration.hookBus must be one of: ' + [...VALID_HOOK_BUSES].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.hookBus) + ')',
+      );
+    }
+
+    // stateIO
+    if (hi.stateIO === '__proto__' || hi.stateIO === 'constructor' || hi.stateIO === 'prototype') {
+      errors.push('runtime.hostIntegration.stateIO "' + hi.stateIO + '" is a reserved name');
+    } else if (hi.stateIO !== 'undocumented' && !VALID_STATE_IO.has(hi.stateIO)) {
+      errors.push(
+        'runtime.hostIntegration.stateIO must be one of: ' + [...VALID_STATE_IO].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.stateIO) + ')',
+      );
+    }
+
+    // transport
+    if (hi.transport === '__proto__' || hi.transport === 'constructor' || hi.transport === 'prototype') {
+      errors.push('runtime.hostIntegration.transport "' + hi.transport + '" is a reserved name');
+    } else if (hi.transport !== 'undocumented' && !VALID_TRANSPORTS.has(hi.transport)) {
+      errors.push(
+        'runtime.hostIntegration.transport must be one of: ' + [...VALID_TRANSPORTS].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.transport) + ')',
+      );
+    }
+
+    // runtime (axis)
+    if (hi.runtime === '__proto__' || hi.runtime === 'constructor' || hi.runtime === 'prototype') {
+      errors.push('runtime.hostIntegration.runtime "' + hi.runtime + '" is a reserved name');
+    } else if (hi.runtime !== 'undocumented' && !VALID_HOST_RUNTIMES.has(hi.runtime)) {
+      errors.push(
+        'runtime.hostIntegration.runtime must be one of: ' + [...VALID_HOST_RUNTIMES].join(', ') +
+        ' (or "undocumented") (got: ' + JSON.stringify(hi.runtime) + ')',
+      );
+    }
+
+    // dispatch — required object
+    if (typeof hi.dispatch !== 'object' || hi.dispatch === null || Array.isArray(hi.dispatch)) {
+      errors.push('runtime.hostIntegration.dispatch must be an object');
+    } else {
+      const d = hi.dispatch;
+
+      // S2b: reserved-OWN-KEY guard on dispatch (CodeQL barrier — inline literal comparisons)
+      if (Object.prototype.hasOwnProperty.call(d, '__proto__')) {
+        errors.push('runtime.hostIntegration.dispatch must not contain reserved key "__proto__"');
+      }
+      if (Object.prototype.hasOwnProperty.call(d, 'constructor')) {
+        errors.push('runtime.hostIntegration.dispatch must not contain reserved key "constructor"');
+      }
+      if (Object.prototype.hasOwnProperty.call(d, 'prototype')) {
+        errors.push('runtime.hostIntegration.dispatch must not contain reserved key "prototype"');
+      }
+
+      // namedDispatch — boolean or 'undocumented'
+      if (typeof d.namedDispatch !== 'boolean' && d.namedDispatch !== 'undocumented') {
+        errors.push(
+          'runtime.hostIntegration.dispatch.namedDispatch must be a boolean or "undocumented" (got: ' + JSON.stringify(d.namedDispatch) + ')',
+        );
+      }
+
+      // nested — boolean or 'undocumented'
+      if (typeof d.nested !== 'boolean' && d.nested !== 'undocumented') {
+        errors.push(
+          'runtime.hostIntegration.dispatch.nested must be a boolean or "undocumented" (got: ' + JSON.stringify(d.nested) + ')',
+        );
+      }
+
+      // background — boolean or 'undocumented'
+      if (typeof d.background !== 'boolean' && d.background !== 'undocumented') {
+        errors.push(
+          'runtime.hostIntegration.dispatch.background must be a boolean or "undocumented" (got: ' + JSON.stringify(d.background) + ')',
+        );
+      }
+
+      // subagentToolkit — closed enum or 'undocumented'
+      if (d.subagentToolkit === '__proto__' || d.subagentToolkit === 'constructor' || d.subagentToolkit === 'prototype') {
+        errors.push('runtime.hostIntegration.dispatch.subagentToolkit "' + d.subagentToolkit + '" is a reserved name');
+      } else if (d.subagentToolkit !== 'undocumented' && !VALID_SUBAGENT_TOOLKITS.has(d.subagentToolkit)) {
+        errors.push(
+          'runtime.hostIntegration.dispatch.subagentToolkit must be one of: ' + [...VALID_SUBAGENT_TOOLKITS].join(', ') +
+          ' (or "undocumented") (got: ' + JSON.stringify(d.subagentToolkit) + ')',
+        );
+      }
+
+      // maxDepth — integer >= -1 or 'undocumented'
+      if (d.maxDepth !== 'undocumented' && (!Number.isInteger(d.maxDepth) || d.maxDepth < -1)) {
+        errors.push(
+          'runtime.hostIntegration.dispatch.maxDepth must be an integer >= -1 or "undocumented" (got: ' + JSON.stringify(d.maxDepth) + ')',
+        );
+      }
+
+      // backgroundDispatch — REQUIRED (all 16 runtime descriptors carry it, matching the sibling fields
+      // namedDispatch/nested/background/subagentToolkit/maxDepth which are all required).
+      if (!Object.prototype.hasOwnProperty.call(d, 'backgroundDispatch')) {
+        errors.push(
+          'runtime.hostIntegration.dispatch.backgroundDispatch is required (must be a boolean or "undocumented")',
+        );
+      } else if (typeof d.backgroundDispatch !== 'boolean' && d.backgroundDispatch !== 'undocumented') {
+        errors.push(
+          'runtime.hostIntegration.dispatch.backgroundDispatch must be a boolean or "undocumented" (got: ' + JSON.stringify(d.backgroundDispatch) + ')',
+        );
+      }
+    }
+  }
+
   // GATE A: installSurface ↔ hooksSurface consistency (DEFECT.GENERATIVE-FIX)
   // Only check if both fields are valid strings (individual field validators above report type errors).
   if (typeof r.installSurface === 'string' && typeof r.hooksSurface === 'string') {
@@ -2045,6 +2246,7 @@ module.exports = {
   VALID_COMMAND_STYLES,
   VALID_HOOKS_SURFACES,
   VALID_HOOK_EVENTS,
+  VALID_EXTENSION_EVENTS,
   VALID_SANDBOX_TIERS,
   VALID_ARTIFACT_KIND_NAMES,
   VALID_ARTIFACT_NESTINGS,
@@ -2052,6 +2254,24 @@ module.exports = {
   VALID_INSTALL_SURFACES,
   VALID_PERMISSION_WRITERS,
   VALID_EXTENDED_HOOK_EVENTS,
+  VALID_EMBEDDING_MODES,
+  VALID_COMMAND_SURFACES,
+  VALID_MODEL_MODES,
+  VALID_HOOK_BUSES,
+  VALID_STATE_IO,
+  VALID_TRANSPORTS,
+  VALID_HOST_RUNTIMES,
+  VALID_SUBAGENT_TOOLKITS,
+  _HOST_INTEGRATION_VOCAB: {
+    embeddingMode:   [...VALID_EMBEDDING_MODES],
+    commandSurface:  [...VALID_COMMAND_SURFACES],
+    modelMode:       [...VALID_MODEL_MODES],
+    hookBus:         [...VALID_HOOK_BUSES],
+    stateIO:         [...VALID_STATE_IO],
+    transport:       [...VALID_TRANSPORTS],
+    runtime:         [...VALID_HOST_RUNTIMES],
+    subagentToolkit: [...VALID_SUBAGENT_TOOLKITS],
+  },
   INSTALL_SURFACE_TO_ALLOWED_HOOKS_SURFACES,
   GEMINI_AGENT_EVENTS,
   CLAUDE_FAMILY_EVENTS,

package/gsd-core/bin/lib/cli-skew-check.cjs

@@ -0,0 +1,44 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCliSkew = checkCliSkew;
+/**
+ * cli-skew-check.cts — CLI version-skew detection (#1754).
+ *
+ * Pure function: compares the resolved gsd-tools.cjs path to the project root.
+ * If the resolved CLI is OUTSIDE the project root while a project-local install
+ * EXISTS, returns a warning string (the caller writes it to stderr). Non-blocking.
+ *
+ * Catches the shadowing scenario from #1748: a stale global canary CLI (e.g.
+ * from the retired @gsd-build/sdk) shadowing the project-local GSD install.
+ *
+ * The function is PURE (no I/O) — the caller provides the resolved path, the
+ * project root, and whether a project-local install exists. This makes it
+ * trivially testable without filesystem setup.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Check for CLI version skew.
+ *
+ * @param opts.resolvedPath - The absolute path of the running gsd-tools.cjs (__filename).
+ * @param opts.projectRoot - The project root (from findProjectRoot), or null if no project.
+ * @param opts.projectLocalExists - Whether a project-local gsd-tools.cjs exists.
+ * @returns A warning string if skew is detected, or null if no skew.
+ */
+function checkCliSkew(opts) {
+    const { resolvedPath, projectRoot, projectLocalExists } = opts;
+    // No project context or no project-local install → no skew possible.
+    if (!projectRoot || !projectLocalExists)
+        return null;
+    // If the resolved CLI is under the project root, it IS a project-local install.
+    const rel = node_path_1.default.relative(projectRoot, resolvedPath);
+    if (!rel.startsWith('..'))
+        return null;
+    // Resolved CLI is outside project root while a project-local install exists → SKEW.
+    const hint = resolvedPath.includes('@gsd-build')
+        ? ' If @gsd-build/sdk: npm uninstall -g @gsd-build/sdk'
+        : '';
+    return `⚠ GSD: ${resolvedPath} may shadow project-local GSD.${hint}`;
+}

package/gsd-core/bin/lib/command-aliases.cjs

@@ -159,6 +159,14 @@ exports.STATE_COMMAND_ALIASES = [
         "subcommand": "prune",
         "mutation": true
     },
+    {
+        "canonical": "state.rebuild",
+        "aliases": [
+            "state rebuild"
+        ],
+        "subcommand": "rebuild",
+        "mutation": true
+    },
     {
         "canonical": "state.milestone-switch",
         "aliases": [

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

@@ -1302,7 +1302,8 @@ function cmdStats(cwd, format, raw) {
         const roadmapContent = extractCurrentMilestone(roadmapRaw, cwd);
         // Matches both plain numeric (Phase 1:) and milestone-prefixed (Phase 2-01:) headings.
         // Also tolerates optional [bracket-token] scope prefix on phase headings.
-        const headingPattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:\s*([^\n]+)/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
         let match;
         while ((match = headingPattern.exec(roadmapContent)) !== null) {
             const key = normalizePhaseName(match[1]);

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

@@ -637,6 +637,33 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         }
         parsedValue = normalized.values;
     }
+    // #1517: validate review.reviewer_instances.<name>.<field> leaves at the
+    // invocation boundary (Postel/Kerckhoffs — strict at accept). The config
+    // schema dynamic pattern admits the path; this block validates the name + the
+    // field value so a misconfigured instance is rejected at config-set time, not
+    // silently at review time. Single-source validators live in
+    // review-reviewer-selection.cjs (INSTANCE_NAME_PATTERN, KNOWN_REVIEWER_SLUGS).
+    const instanceLeaf = kp.match(/^review\.reviewer_instances\.([a-zA-Z0-9_-]+)\.(cli|model|agent)$/);
+    if (instanceLeaf) {
+        const [, instanceName, field] = instanceLeaf;
+        if (!review_reviewer_selection_cjs_1.INSTANCE_NAME_PATTERN.test(instanceName)) {
+            error(`Invalid reviewer instance name '${instanceName}'. Must match ^[a-z0-9][a-z0-9-]*$.`);
+        }
+        if (review_reviewer_selection_cjs_1.KNOWN_REVIEWER_SLUGS.includes(instanceName)) {
+            error(`Reviewer instance name '${instanceName}' must not equal a built-in reviewer slug.`);
+        }
+        if (field === 'cli') {
+            if (typeof parsedValue !== 'string' || !review_reviewer_selection_cjs_1.KNOWN_REVIEWER_SLUGS.includes(parsedValue)) {
+                error(`Invalid reviewer_instances.${instanceName}.cli '${val}'. Must be a known reviewer adapter: ${review_reviewer_selection_cjs_1.KNOWN_REVIEWER_SLUGS.join(', ')}.`);
+            }
+        }
+        else {
+            // model | agent — opaque pass-through strings (never interpolated into shell).
+            if (typeof parsedValue !== 'string') {
+                error(`Invalid reviewer_instances.${instanceName}.${field} '${val}'. Must be a string.`);
+            }
+        }
+    }
     const setConfigValueResult = setConfigValue(cwd, kp, parsedValue);
     // Mask secrets in both JSON and text output. The plaintext is written
     // to config.json (that's where secrets live on disk); the CLI output

package/gsd-core/bin/lib/embedding-adapter.cjs

@@ -0,0 +1,27 @@
+/**
+ * Embedding adapter contract — the common `HostIntegrationInterface` both
+ * embedding adapters satisfy (ADR-1239 Phase C-1, #1680).
+ *
+ * INTENTIONALLY MINIMAL (Phase 3 slice 1). The full six-interface-point binding
+ * surface (command / dispatch / model / hooks / state / artifact) is DEFERRED
+ * until the imperative adapter (AC2) provides a real consumer that fixes the
+ * shape — ADR-1239 lists the wire-shape as an open question:
+ *   "Exact wire-shape of the initialize handshake … Where precisely to cut the
+ *    engine↔host boundary"
+ * (docs/adr/1239-gsd-embeddable-orchestration-engine.md#open-questions-narrowed-by-the-research).
+ * Freezing a 6-point contract before the imperative adapter exists would risk
+ * rework across Phases 3-6. This slice ships only what the declarative adapter
+ * (AC1) needs: the kind discriminator + runtime + install/uninstall entry.
+ *
+ * Both adapters bind the SAME engine (install-engine.cjs / the loop resolver);
+ * they differ in HOW — declarative projects files (lossy: drops loop
+ * orchestration), imperative drives host primitives in-process. See ADR-1239
+ * "How a capability reaches a host (two adapters, one engine)".
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_KINDS = void 0;
+// ---------------------------------------------------------------------------
+// Kinds
+// ---------------------------------------------------------------------------
+exports.ADAPTER_KINDS = Object.freeze(['declarative', 'imperative']);

package/gsd-core/bin/lib/external-descriptor-trust.cjs

@@ -0,0 +1,70 @@
+/**
+ * External-descriptor trust gate (ADR-1239 Phase C-2, #1681).
+ *
+ * Load-time `configHome` write-confinement for installed third-party host-plugin
+ * descriptors. The opt-in loader (`loadRegistry({includeInstalled:true})`) already
+ * applies schema validation + consent + first-party-wins + fail-closed gates;
+ * this adds defense-in-depth: **before** a third-party descriptor's install plan
+ * is ever executed, assert every destSubpath it declares resolves within the
+ * user-approved `configHome`. A path-escaping or malformed descriptor is
+ * rejected fail-closed.
+ *
+ * This is the load-time twin of Phase 2's install-time gate
+ * (`assertDestWithinConfigHome` in runtime-artifact-install-plan.cts, #1679 AC3).
+ * The two are defense-in-depth: load-time rejects malformed descriptors early
+ * (before consent even matters); install-time bounds the actual writes.
+ *
+ * Do NOT conflate with ADR-1577's prompt-injection circuit-breaker — separate
+ * concern sharing the word "trust".
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathConfined = isPathConfined;
+exports.assertDescriptorConfined = assertDescriptorConfined;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Pure path-containment check (cross-platform). `target` is confined to `root`
+ * iff resolving it relative to `root` yields a path equal to or under `root`.
+ * Absolute paths outside `root` and `..`-escapes return false.
+ */
+function isPathConfined(target, root) {
+    if (typeof target !== 'string' || typeof root !== 'string' || target.length === 0 || root.length === 0) {
+        return false;
+    }
+    const rootResolved = node_path_1.default.resolve(root);
+    const targetResolved = node_path_1.default.resolve(root, target);
+    const prefix = rootResolved + node_path_1.default.sep;
+    return targetResolved === rootResolved || targetResolved.startsWith(prefix);
+}
+/**
+ * Assert every destSubpath the descriptor declares (global + local artifact
+ * layout) resolves within `configHome`. Throws fail-closed naming the offending
+ * descriptor + path on the first escape. A descriptor with no artifact layout
+ * passes (nothing to confine).
+ */
+function assertDescriptorConfined(descriptor, configHome) {
+    if (!descriptor || typeof descriptor !== 'object')
+        return;
+    const id = typeof descriptor.id === 'string' ? descriptor.id : '<unknown>';
+    const layout = descriptor.runtime?.artifactLayout;
+    if (!layout || typeof layout !== 'object')
+        return;
+    const check = (scope, kinds) => {
+        if (!Array.isArray(kinds))
+            return;
+        for (const kind of kinds) {
+            const dest = kind?.destSubpath;
+            if (typeof dest !== 'string' || dest.length === 0)
+                continue;
+            if (!isPathConfined(dest, configHome)) {
+                throw new Error(`external-descriptor-trust: descriptor '${id}' declares an unconfined ${scope} destSubpath ` +
+                    `${JSON.stringify(dest)} (resolves outside configHome ${JSON.stringify(configHome)}) — rejected fail-closed.`);
+            }
+        }
+    };
+    check('global', layout.global);
+    check('local', layout.local);
+}

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

@@ -126,6 +126,49 @@ function extractFrontmatter(content) {
     }
     return frontmatter;
 }
+/**
+ * Escape a string for emission inside a YAML double-quoted scalar (#1779).
+ * Backslash must be escaped first so the backslashes added for embedded quotes
+ * (and control chars) are not themselves doubled. Without this, a value
+ * carrying an indicator (`:`/`#`) that also contains a literal `"` serializes
+ * to invalid YAML, e.g. `upstream: "https://x (Tom; "Git. Ship. Done")"`. A
+ * literal newline/tab/control char inside the quotes likewise breaks (or
+ * silently alters) the scalar, so those are escaped to their YAML forms too.
+ */
+function escapeDoubleQuoted(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t')
+        .replace(/\r/g, '\\r')
+        // Remaining C0 controls + DEL → \xHH (a valid YAML double-quoted escape).
+        .replace(/[\u0000-\u001f\u007f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+/**
+ * A plain (unquoted) scalar that would mis-parse or round-trip lossily when
+ * emitted bare must instead go through the double-quoted + escaped form
+ * (#1779): the empty string (bare `k:` reloads as null), an embedded `"`/`\`
+ * or control char, a leading YAML indicator (quote, `&`/`*`/`!` anchor/alias/
+ * tag, `|`/`>` block scalar, flow `[]{},`, `#`, reserved `%`/`@`/backtick, or
+ * `-`/`?`/`:` before a space), or leading/trailing whitespace. This helper is
+ * the correctness complement of `escapeDoubleQuoted`: it broadens the *trigger*
+ * for quoting without broadening the lossy object-list handling deferred to
+ * #1572/#1660.
+ */
+function scalarNeedsDoubleQuoting(s) {
+    if (s === '')
+        return true;
+    if (/["\\\u0000-\u001f\u007f]/.test(s))
+        return true;
+    // Always-unsafe leading indicators, or leading/trailing whitespace.
+    if (/^[,[\]{}#&*!|>'"%@`]/.test(s) || /^\s|\s$/.test(s))
+        return true;
+    // `-` `?` `:` only start a plain scalar safely when NOT followed by a space.
+    if (/^[-?:](\s|$)/.test(s))
+        return true;
+    return false;
+}
 function reconstructFrontmatter(obj) {
     const lines = [];
     for (const [key, value] of Object.entries(obj)) {
@@ -141,7 +184,7 @@ function reconstructFrontmatter(obj) {
             else {
                 lines.push(`${key}:`);
                 for (const item of value) {
-                    lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                    lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#') || scalarNeedsDoubleQuoting(item)) ? `"${escapeDoubleQuoted(item)}"` : item}`);
                 }
             }
         }
@@ -160,7 +203,7 @@ function reconstructFrontmatter(obj) {
                     else {
                         lines.push(`  ${subkey}:`);
                         for (const item of subval) {
-                            lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                            lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#') || scalarNeedsDoubleQuoting(item)) ? `"${escapeDoubleQuoted(item)}"` : item}`);
                         }
                     }
                 }
@@ -189,14 +232,14 @@ function reconstructFrontmatter(obj) {
                 else {
                     // eslint-disable-next-line @typescript-eslint/no-base-to-string
                     const sv = String(subval);
-                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) ? `"${escapeDoubleQuoted(sv)}"` : sv}`);
                 }
             }
         }
         else {
             const sv = String(value);
-            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
-                lines.push(`${key}: "${sv}"`);
+            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv)) {
+                lines.push(`${key}: "${escapeDoubleQuoted(sv)}"`);
             }
             else {
                 lines.push(`${key}: ${sv}`);
@@ -448,7 +491,11 @@ function parseMustHavesBlock(content, blockName) {
             else {
                 const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
                 if (kvMatch) {
-                    const val = kvMatch[2];
+                    // Trim: a quoted value like `"backstop "` captures the inner trailing space in group 2.
+                    // Left untrimmed, a hand-authored `must_haves` marker degrades (a `backstop` truth silently
+                    // grades green instead of abstaining — #1905, the #1154 false-pass; also the sibling
+                    // check_target/violationFixture path). Whitespace is never semantic in a scalar KV value.
+                    const val = kvMatch[2].trim();
                     // Try to parse as number
                     (current)[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
                 }