@opengsd/gsd-core 1.6.0 → 1.7.0-rc.1

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

@@ -594,13 +594,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 +611,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

@@ -713,6 +713,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([
@@ -1020,6 +1030,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 +1061,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') {
@@ -2052,6 +2232,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/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/hook-bus.cjs

@@ -0,0 +1,81 @@
+/**
+ * Hook-bus seam (ADR-1239 Phase C-1, AC4 / #1680).
+ *
+ * The lifecycle-hook ownership model, selected by the negotiated `hookBus`
+ * axis (host-integration.cts):
+ *
+ *   - `engine` — GSD owns the bus internally (in-process pub/sub). Used by
+ *     hosts that have no event bus (VS Code). Full subscribe + emit.
+ *   - `host`   — the host fires events; GSD subscribes. Handlers register
+ *     locally for a Phase-5 host binding to dispatch to; `emit` delegates to a
+ *     host-supplied emitter (fail-closed until bound — GSD does not drive a
+ *     host-owned bus).
+ *   - `none`   — no bus (Cline-rules). Degrades to rule-text instructions;
+ *     subscribe/emit are no-ops.
+ *
+ * Portable event floor — the "claude dialect" all hook-capable hosts share
+ * (sourced from src/runtime-hooks-surface.cts). Extended events are negotiated
+ * per-host (Phase 5).
+ *
+ * Minimal seam (per ADR-1239 open wire-shape question): the host-side dispatch
+ * wiring lands in Phase 5 (#1682). This slice ships the three ownership modes
+ * + the engine pub-sub + the fail-closed contract.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PORTABLE_EVENT_FLOOR = void 0;
+exports.createHookBus = createHookBus;
+exports.PORTABLE_EVENT_FLOOR = Object.freeze(['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd']);
+function createHookBus({ bus }, options = {}) {
+    if (bus !== 'host' && bus !== 'engine' && bus !== 'none') {
+        throw new TypeError(`createHookBus: bus must be 'host' | 'engine' | 'none' (got ${JSON.stringify(bus)})`);
+    }
+    if (bus === 'none') {
+        return Object.freeze({
+            bus,
+            subscribe() { },
+            emit() { },
+        });
+    }
+    if (bus === 'engine') {
+        const subs = new Map();
+        return Object.freeze({
+            bus: 'engine',
+            subscribe(event, handler) {
+                const list = subs.get(event);
+                if (list)
+                    list.push(handler);
+                else
+                    subs.set(event, [handler]);
+            },
+            emit(event, payload) {
+                const list = subs.get(event);
+                if (!list)
+                    return;
+                for (const h of list) {
+                    // Handler errors are isolated — one throwing handler must not break the bus.
+                    try {
+                        h(payload);
+                    }
+                    catch { /* swallow; bus stays up */ }
+                }
+            },
+        });
+    }
+    // host: GSD subscribes; emits go to the host-supplied emitter (fail-closed until bound).
+    const hostEmit = options.hostEmit;
+    return Object.freeze({
+        bus: 'host',
+        subscribe(_event, _handler) {
+            // Host owns the bus; GSD's subscriptions are dispatched by a Phase-5 host
+            // binding that calls the registered handlers when the host fires events.
+            // Stored host-side; locally this is a seam until that binding lands.
+        },
+        emit(event, payload) {
+            if (typeof hostEmit !== 'function') {
+                throw new Error("host hook-bus emit: no host emitter bound — the 'host' bus requires a hostEmit primitive (Phase 5 wires the concrete host).");
+            }
+            hostEmit(event, payload);
+        },
+    });
+}