@opengsd/gsd-core 1.15.0 → 1.16.0

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

@@ -15,9 +15,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.RetiredRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.FALLBACK_HOST_BEHAVIORS = exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = exports.RetiredRuntimeError = exports.UnknownRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
 exports.isRetiredRuntimeId = isRetiredRuntimeId;
 exports.assertNotRetiredRuntime = assertNotRetiredRuntime;
+exports.isKnownRuntimeId = isKnownRuntimeId;
+exports.assertKnownRuntime = assertKnownRuntime;
+exports.hostBehaviorsFor = hostBehaviorsFor;
 exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
@@ -25,7 +28,6 @@ exports.getDirName = getDirName;
 exports.getRuntimeLabel = getRuntimeLabel;
 exports.getGlobalConfigHomeFragment = getGlobalConfigHomeFragment;
 exports.runtimeFlags = runtimeFlags;
-exports.getRuntimeNewProjectCommand = getRuntimeNewProjectCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 /**
@@ -92,6 +94,22 @@ const RETIRED_RUNTIME_SPELLINGS = new Map(Array.from(RETIRED_RUNTIME_DETAILS.key
  * with like.
  */
 exports.RETIRED_RUNTIME_IDS = new Set(RETIRED_RUNTIME_DETAILS.keys());
+/**
+ * Error thrown when a non-empty runtime id that is neither registered nor a
+ * known non-registry host reaches a descriptor accessor (ADR-5057 §5, #5169).
+ * Before this, such an id silently resolved to Claude Code's values.
+ */
+class UnknownRuntimeError extends Error {
+    code = 'GSD_UNKNOWN_RUNTIME';
+    runtimeId;
+    constructor(runtimeId) {
+        super(`Runtime "${runtimeId}" is not registered in the capability registry. `
+            + 'Refusing to resolve it, because the previous behaviour silently returned Claude Code\'s values.');
+        this.name = 'UnknownRuntimeError';
+        this.runtimeId = runtimeId;
+    }
+}
+exports.UnknownRuntimeError = UnknownRuntimeError;
 /** Error thrown when a retired runtime id reaches a resolution accessor. */
 class RetiredRuntimeError extends Error {
     code = 'GSD_RETIRED_RUNTIME';
@@ -127,6 +145,120 @@ function assertNotRetiredRuntime(runtime) {
         return;
     throw new RetiredRuntimeError(id, detail);
 }
+/**
+ * Legacy runtime ids that have a genuine, dedicated resolution branch in
+ * `runtime-homes.cts` but no capability-registry descriptor (#3024). They are
+ * KNOWN ids: every accessor resolves them rather than refusing. Enumerated by
+ * hand and MUST stay in lockstep with `getGlobalConfigDir`'s hardcoded
+ * branches — add an id only after confirming it has a real dedicated branch.
+ */
+exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = Object.freeze({
+    // Grok's agents home: `GROK_AGENTS_HOME`, else `~/.agents` (dir = path segments under $HOME).
+    grok: Object.freeze({ env: 'GROK_AGENTS_HOME', dir: Object.freeze(['.agents']) }),
+});
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = new Set(Object.keys(exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES));
+/** The capability registry's `runtimes` map, or `null` when it fails to load. */
+function loadRegistryRuntimes() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const reg = require('./capability-registry.cjs');
+        return (reg && reg.runtimes) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `runtime` is a registered runtime id (own property of the registry
+ * `runtimes` map — never an inherited key such as `__proto__`/`constructor`)
+ * or one of {@link LEGACY_NON_REGISTRY_RUNTIME_IDS}. Raw-id match: no trimming,
+ * no case folding, no alias expansion.
+ */
+function isKnownRuntimeId(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return false;
+    const runtimes = loadRegistryRuntimes();
+    if (runtimes && Object.prototype.hasOwnProperty.call(runtimes, runtime))
+        return true;
+    return exports.LEGACY_NON_REGISTRY_RUNTIME_IDS.has(runtime);
+}
+/**
+ * The ONE refusal every descriptor accessor shares (ADR-5057 §5, #5169).
+ * No-op for an absent id (`''`, non-string): that is the documented
+ * "no runtime selected" generic path. A retired id throws
+ * {@link RetiredRuntimeError}; any other non-empty id that is not known throws
+ * {@link UnknownRuntimeError} instead of silently resolving to Claude Code's
+ * values. When the registry itself failed to load, unknown-ness cannot be
+ * proven, so the check degrades to a no-op (the #338 floor in
+ * {@link hostBehaviorsFor} still protects the reference host).
+ */
+function assertKnownRuntime(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return;
+    assertNotRetiredRuntime(runtime);
+    if (loadRegistryRuntimes() === null)
+        return;
+    if (!isKnownRuntimeId(runtime))
+        throw new UnknownRuntimeError(runtime);
+}
+/**
+ * The #338-privacy fail-safe floor: host behaviors for the two hosts whose
+ * generic fallthrough would be WRONG if the registry failed to load. Moved
+ * here from `bin/install.js` so the registry-load-failure degrade lives in the
+ * single host-behaviors accessor instead of one of three copies (#5169).
+ */
+exports.FALLBACK_HOST_BEHAVIORS = Object.freeze({
+    claude: Object.freeze({
+        settingsFileByScope: Object.freeze({ local: 'settings.local.json', global: 'settings.json' }),
+        permissionsSchema: 'claude',
+        sourceMarkerFile: '.gsd-source',
+        hyphenNameAgentBody: true,
+        legacyCommandsGsdInstallMigration: true,
+        legacyCommandsGsdUninstall: 'global',
+    }),
+    // antigravity's global config dir is resolved dynamically (env-overridable,
+    // multi-segment); this floor keeps that routing intact if the registry fails
+    // to load instead of falling through to the wrong '.claude' fragment (#2096).
+    antigravity: Object.freeze({ globalDirResolver: 'antigravity' }),
+});
+/**
+ * The single accessor for a runtime's host behaviors
+ * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors). Replaces
+ * the three private `_hostBehaviors` copies in `bin/install.js`,
+ * `install-engine.cts` and `runtime-artifact-conversion.cts`.
+ *
+ * - absent id (`''`, non-string) → `{}` (generic path).
+ * - registered id → the descriptor's `hostBehaviors` (or `{}` when it declares
+ *   none).
+ * - known non-registry id (`grok`) → `{}`.
+ * - registry failed to load → the #338 floor for the ids it covers, else `{}`.
+ * - any other id (unregistered, retired, a prototype key) → `{}`: no declared
+ *   behaviors, which is the GENERIC path — never Claude Code's behaviors.
+ *
+ * Unlike the path/label accessors (`getDirName`, `getGlobalConfigDir`, …), whose
+ * fallthrough answer is Claude Code's value and therefore a silent wrong answer
+ * (#4632), an absent behavior is the correct answer for a label GSD does not
+ * know — and this accessor is read by guard and hook code on user-supplied
+ * runtime labels (stale config, a retired id), where a throw would crash the
+ * session rather than skip a behavior. ADR-5057 §5 Phase 10 amendment.
+ *
+ * `registry` is injectable so the load-failure branch is unit-testable.
+ */
+function hostBehaviorsFor(runtime, registry) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return {};
+    const floor = () => Object.prototype.hasOwnProperty.call(exports.FALLBACK_HOST_BEHAVIORS, runtime)
+        ? exports.FALLBACK_HOST_BEHAVIORS[runtime]
+        : {};
+    const runtimes = registry === undefined ? loadRegistryRuntimes() : (registry && registry.runtimes) || null;
+    if (runtimes === null)
+        return floor();
+    if (Object.prototype.hasOwnProperty.call(runtimes, runtime)) {
+        const declared = runtimes[runtime]?.runtime?.hostBehaviors;
+        return declared ? declared : floor();
+    }
+    return {};
+}
 const FALLBACK_ALIASES = {
     claude: ['claude', 'claude-code', 'claude-cli'],
     opencode: ['opencode', 'open-code', 'opencode-cli'],
@@ -302,7 +434,7 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
 function getDirName(runtime) {
     // Same silent-wrong-answer class as the four accessors AC#1 names: this
     // returned '.claude' for a retired id, and it feeds runtimeConfigDir.
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return '.claude';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -373,7 +505,7 @@ const RUNTIME_LABELS = {
  * 'Claude Code'. Sibling to `getDirName`; pure (no I/O).
  */
 function getRuntimeLabel(runtime) {
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return 'Claude Code';
     const label = RUNTIME_LABELS[runtime];
@@ -429,7 +561,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
  * dynamically). Pure: no I/O. Sibling to `getDirName` / `getRuntimeLabel`.
  */
 function getGlobalConfigHomeFragment(runtime) {
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return DEFAULT_CONFIG_HOME_FRAGMENT;
     const frag = GLOBAL_CONFIG_HOME_FRAGMENTS[runtime];
@@ -475,25 +607,8 @@ function runtimeFlags(runtime) {
     }
     return Object.freeze(flags);
 }
-/**
- * The `/gsd-new-project` invocation syntax per runtime — the post-install
- * "next step" command string. Most runtimes use the default `/gsd-new-project`;
- * a few hosts need a different surface syntax. Collapses the 14-line
- * `if (runtime === 'x') command = ...` chain in bin/install.js's next-step
- * message (ADR-1239 Phase B / #1679 AC2). Pure: no I/O.
- */
-const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
-const RUNTIME_NEW_PROJECT_COMMANDS = {
-    codex: '$gsd-new-project',
-    cursor: 'gsd-new-project (mention the skill name)',
-    kimi: '/skill:gsd-new-project',
-};
-function getRuntimeNewProjectCommand(runtime) {
-    // Deliberately NOT retirement-guarded: this value does not vary by runtime
-    // in a way that makes a retired id a WRONG answer, so throwing here would
-    // cost callers a crash without correcting anything.
-    if (!runtime)
-        return DEFAULT_NEW_PROJECT_COMMAND;
-    const c = RUNTIME_NEW_PROJECT_COMMANDS[runtime];
-    return typeof c === 'string' && c.length > 0 ? c : DEFAULT_NEW_PROJECT_COMMAND;
-}
+// The `/gsd-new-project` next-step command is no longer a per-runtime table
+// here: it is generated from the runtime's registered trigger surface by
+// `resolveAdvertisedNewProject` (runtime-artifact-layout.cts, #5215, ADR-5057
+// §5 Phase 12), so what the installer advertises cannot differ from what a
+// runtime registered.

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -34,6 +34,7 @@ exports._setInstallRuntimeMarkerForTests = _setInstallRuntimeMarkerForTests;
 exports._resetInstallRuntimeMarkerCacheForTests = _resetInstallRuntimeMarkerCacheForTests;
 exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
+exports.resolveActiveRuntime = resolveActiveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -148,31 +149,36 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
     const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME']);
     if (envRuntime)
         return envRuntime;
-    if (projectDir) {
-        try {
-            // Read config.json directly (not via loadConfig). loadConfig has a side
-            // effect of normalizing and re-writing legacy keys back to disk, which
-            // would mutate the project file just to read the runtime name. We only
-            // need the literal `runtime:` value, so a plain JSON read is sufficient
-            // and side-effect-free.
-            const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
-            if (node_fs_1.default.existsSync(configPath)) {
-                const raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
-                const parsed = JSON.parse(raw);
-                if (parsed && typeof parsed === 'object' && 'runtime' in parsed) {
-                    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(parsed['runtime']);
-                    if (configRuntime)
-                        return configRuntime;
-                }
-            }
-        }
-        catch {
-            // Fall through to default — a missing/broken config must not crash
-            // runtime output formatting.
-        }
-    }
+    const config = readProjectConfig(projectDir);
+    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(config ? config['runtime'] : undefined);
+    if (configRuntime)
+        return configRuntime;
     return null;
 }
+/**
+ * Read `<projectDir>/.planning/config.json` as a plain object, or `null` when
+ * there is no project, no file, or it is unreadable or not an object.
+ *
+ * Read directly (not via loadConfig). loadConfig has a side effect of
+ * normalizing and re-writing legacy keys back to disk, which would mutate the
+ * project file just to read the runtime name. A plain JSON read is sufficient
+ * and side-effect-free. A missing or broken config must not crash runtime
+ * output formatting, so every failure degrades to `null`.
+ */
+function readProjectConfig(projectDir) {
+    if (!projectDir)
+        return null;
+    try {
+        const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+        if (!node_fs_1.default.existsSync(configPath))
+            return null;
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the effective runtime for a project directory.
  *
@@ -195,13 +201,24 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
  * @returns the resolved runtime name
  */
 function resolveRuntime(projectDir) {
-    const explicit = resolveExplicitRuntime(projectDir);
-    if (explicit)
-        return explicit;
-    const markerRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(readInstallRuntimeMarker());
-    if (markerRuntime)
-        return markerRuntime;
-    return 'claude';
+    // The same chain `resolveActiveRuntime` owns, fed by a project directory:
+    // one implementation, so the two entry points cannot drift (#5169).
+    return resolveActiveRuntime(readProjectConfig(projectDir));
+}
+/**
+ * Resolve the effective runtime from an ALREADY-LOADED config object — the one
+ * chain every consumer of "which runtime is this install" shares (#5169,
+ * ADR-5057 §5, #4690):
+ *
+ *   env.GSD_RUNTIME  >  config.runtime  >  install marker  >  'claude'
+ *
+ * Canonicalized, so an alias or case variant (`claude-code`, `Claude`) cannot
+ * defeat a downstream comparison. `resolveRuntime` above is the same chain for
+ * callers that hold a project directory rather than a parsed config; the marker
+ * is read through `readInstallRuntimeMarker` in both.
+ */
+function resolveActiveRuntime(config, env = process.env) {
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME'], config ? config['runtime'] : undefined, readInstallRuntimeMarker()) || 'claude';
 }
 /**
  * Convenience: format using the runtime resolved from a project directory.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -64,6 +64,8 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
 const pattern_cjs_1 = require("./pattern.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -146,7 +148,10 @@ function formatHookCommandForRuntime(command, opts = {}) {
 // path missed this guard and reintroduced the #166/#377 failure (#580).
 function shellHookOmitsBashRunner({ platform, runtime = 'generic', isShellHook = false } = {}) {
     const p = platform ?? process.platform;
-    return p === 'win32' && runtime === 'claude' && isShellHook;
+    // #5169: descriptor-declared (`hostBehaviors.omitBashRunnerOnWindows`). The
+    // `'generic'` default and any other non-registered label declares nothing, so
+    // it never omits the runner, exactly as before.
+    return p === 'win32' && isShellHook && (0, runtime_name_policy_cjs_1.hostBehaviorsFor)(runtime).omitBashRunnerOnWindows === true;
 }
 // Builds the command string for a local-install managed `.sh` hook. Mirrors the
 // global buildHookCommand path but uses the $CLAUDE_PROJECT_DIR-anchored prefix
@@ -1033,16 +1038,39 @@ function probeTty(opts = {}) {
     }
 }
 // ─── Platform file I/O ────────────────────────────────────────────────────────
+/**
+ * How many leading lines of LF-only `text` are its closed YAML frontmatter block (opening
+ * fence through closing fence), or 0 when there is none (an unterminated block is not
+ * frontmatter). The fence is `locateFrontmatterFence`'s — the one owner the frontmatter reader
+ * and writer (`frontmatter.cts`) also read — so the normalizer skips exactly the block every
+ * reader sees (found while implementing #5105: this was a private mirror of the reader's
+ * fence rule, because `frontmatter.cts` imports this module, and the two drifted).
+ */
+function leadingFrontmatterLineCount(text) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(text);
+    if (!fence || !fence.closed)
+        return 0;
+    // The lines before the closing fence, plus the closing fence line itself.
+    return text.slice(0, fence.closingStart).split('\n').length;
+}
 function _normalizeMd(content) {
     if (!content || typeof content !== 'string')
         return content;
     let text = content.replace(/\r\n/g, '\n');
     const lines = text.split('\n');
+    // The frontmatter block is YAML, not markdown: its lines are published exactly as written.
+    // A `# comment` is not a heading, and a blank line inserted into a multi-line quoted scalar
+    // or removed from a block scalar changes the value (found while implementing #5105).
+    const frontmatterLines = leadingFrontmatterLineCount(text);
     const result = [];
     const fenceRegex = /^```/;
     const insideFence = new Array(lines.length);
     let fenceOpen = false;
     for (let i = 0; i < lines.length; i++) {
+        if (i < frontmatterLines) {
+            insideFence[i] = false;
+            continue;
+        }
         if (fenceRegex.test(lines[i].trimEnd())) {
             if (fenceOpen) {
                 insideFence[i] = false;
@@ -1059,6 +1087,10 @@ function _normalizeMd(content) {
     }
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (i < frontmatterLines) {
+            result.push(line);
+            continue;
+        }
         const prev = i > 0 ? lines[i - 1] : '';
         const prevTrimmed = prev.trimEnd();
         const trimmed = line.trimEnd();
@@ -1089,8 +1121,11 @@ function _normalizeMd(content) {
                 result.push('');
         }
     }
+    // The frontmatter lines are `result`'s first entries, unchanged; the blank-run collapse
+    // applies from the line ending that closes the block onward.
+    const head = result.slice(0, frontmatterLines).join('\n');
     text = result.join('\n');
-    text = text.replace(/\n{3,}/g, '\n\n');
+    text = head + text.slice(head.length).replace(/\n{3,}/g, '\n\n');
     text = text.replace(/\n*$/, '\n');
     return text;
 }

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

@@ -55,7 +55,7 @@ const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
-const { extractFrontmatter } = frontmatter;
+const { extractFrontmatter, frontmatterBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
 const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
@@ -71,6 +71,10 @@ const { readStateHeadFreshness } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInput = require("./unusable-input.cjs");
 const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
+// #5118: the verification-status owner's frontmatter-only report check.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
+const { findVerificationStatusError } = verificationMod;
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * Staleness threshold for idle-stranded detection. A clean tree whose last
@@ -285,11 +289,20 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     catch {
         return false;
     }
+    // #5118: this phase's VERIFICATION report `status` is judged by its owner
+    // (src/verification.cts, the same frontmatter-only, containment-checked
+    // locator every reader shares) — an out-of-set value is the owner's hard
+    // error here as at every other reader, never a silent "not failed". The
+    // body `STATUS:` marker scan below is this probe's own signal.
+    const statusError = findVerificationStatusError([latestDir]);
+    if (statusError)
+        throw statusError;
     const candidates = files.filter((f) => /summary|verif(?:y|ication)|uat/i.test(f));
     for (const name of candidates) {
         let content = '';
+        const filePath = node_path_1.default.join(latestDir, name);
         try {
-            content = node_fs_1.default.readFileSync(node_path_1.default.join(latestDir, name), 'utf-8');
+            content = node_fs_1.default.readFileSync(filePath, 'utf-8');
         }
         catch {
             continue;
@@ -311,7 +324,10 @@ function readStateFile(statePath) {
         return null;
     }
     const fm = extractFrontmatter(content, statePath);
-    const body = content.replace(/^---[\s\S]*?---\s*/, '');
+    // The body starts after the block `extractFrontmatter` just read (the one fence owner), so a
+    // `---` inside a value, a BOM, or an adjacent empty block cannot cut it somewhere else.
+    const block = frontmatterBlock(content);
+    const body = block ? block.rest.replace(/^\s+/, '') : content;
     return { fm, body };
 }
 /** Collect the full signal set from disk for `cwd`. Exported for unit tests. */

package/gsd-core/bin/lib/stale-bake-guard.cjs

@@ -21,22 +21,23 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const capabilityRegistry = require('./capability-registry.cjs');
+const { hostBehaviorsFor } = require('./runtime-name-policy.cjs');
+const { resolveConfigHomeFromDescriptor } = require('./runtime-homes.cjs');
+const { resolveActiveRuntime } = require('./runtime-slash.cjs');
 
 /**
- * Runtimes whose agent config is static frontmatter/TOML baked at install time.
- * MUST stay in sync with the bake paths in bin/install.js. The parity test in
- * tests/stale-bake-guard.test.cjs asserts this matches the runtimes that
- * actually emit a baked model: line id #2256 (opencode), #49/#2256 (codex),
- * and #2093 (kilo).
+ * Runtimes whose agent config is static frontmatter/TOML baked at install time,
+ * DERIVED from the runtime descriptors (`hostBehaviors.bakesStaticAgentModel`,
+ * #5169) instead of a hand-kept list: line id #2256 (opencode), #49/#2256
+ * (codex), and #2093 (kilo) declare it, and a new baking runtime does too.
  */
-const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'kilo', 'opencode']);
+const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(
+  Object.keys(capabilityRegistry.runtimes)
+    .filter((id) => hostBehaviorsFor(id).bakesStaticAgentModel === true)
+    .sort(),
+);
 
-/** Per-runtime `gsd install` flag, for the remediation hint in the warning. */
-const INSTALL_FLAG_BY_RUNTIME = Object.freeze({
-  codex: '--codex',
-  opencode: '--opencode',
-  kilo: '--kilo',
-});
 
 const _warnedKeys = new Set();
 
@@ -64,7 +65,7 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
   const signal = detectStaleBake({ runtime, configMtimeMs, agentMtimeMs });
   if (!signal) return '';
   const configDate = new Date(configMtimeMs).toISOString();
-  const installFlag = INSTALL_FLAG_BY_RUNTIME[runtime] || `--${runtime}`;
+  const installFlag = `--${runtime}`;
   return [
     `gsd: model config in ${configPath} changed since agents were last baked (${configDate}).`,
     `     Static-frontmatter runtime '${runtime}' ignores the new model_overrides`,
@@ -74,44 +75,27 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
 }
 
 /**
- * Pure: resolve the active runtime id from a parsed config object.
- * Returns the runtime string, or `'claude'` when unset (the spawn-time default
- * for which the guard is a no-op).
+ * Resolve the active runtime id for the guard: the SAME chain every consumer of
+ * "which runtime is this install" reads — GSD_RUNTIME → config.runtime →
+ * per-install `.gsd-runtime` marker → `'claude'` (#5169, #4690). Returns
+ * `'claude'` when nothing is declared (the spawn-time default for which the
+ * guard is a no-op).
  */
-function resolveRuntimeFromConfig(config) {
-  if (config && typeof config === 'object'
-      && typeof config.runtime === 'string' && config.runtime) {
-    return config.runtime;
-  }
-  return 'claude';
+function resolveRuntimeFromConfig(config, env = process.env) {
+  return resolveActiveRuntime(config, env);
 }
 
 /**
- * Resolve the install root for a runtime's agent files, honoring the same env
- * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR, KILO_CONFIG_DIR).
- * Returns the absolute directory or `null` for unsupported runtimes.
+ * Resolve the install root for a runtime's agent files from the runtime
+ * descriptor's `configHome` (the same resolution the installer uses), then
+ * append `agents` — the installer writes agents to `<configHome>/agents`
+ * (plural; #2093). Returns the absolute directory or `null` for runtimes that
+ * do not bake a static agent model.
  */
 function resolveAgentDir(runtime, { env = process.env, homedir = os.homedir } = {}) {
-  if (runtime === 'opencode') {
-    const base = (env.OPENCODE_CONFIG_DIR && String(env.OPENCODE_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'opencode');
-    // #2093 fix: the installer writes agents to `<base>/agents` (plural — see
-    // bin/install.js's universal `agentsDest = path.join(targetDir, 'agents')`,
-    // verified against a live `--opencode --global` install). The prior
-    // singular `agent` never matched the real install output, so this guard's
-    // `findOldestAgentMtime` always hit ENOENT and warnIfStaleBake was a
-    // silent no-op for opencode in production — discovered while wiring the
-    // parallel kilo entry below (same bake mechanism, #2093).
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'kilo') {
-    const base = (env.KILO_CONFIG_DIR && String(env.KILO_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'kilo');
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'codex') {
-    const base = (env.CODEX_HOME && String(env.CODEX_HOME).trim()) || path.join(homedir(), '.codex');
-    return path.join(base, 'agents');
-  }
-  return null;
+  if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return null;
+  const configHome = capabilityRegistry.runtimes[runtime].runtime.configHome;
+  return path.join(resolveConfigHomeFromDescriptor(configHome, { env, home: homedir() }), 'agents');
 }
 
 /**
@@ -168,8 +152,8 @@ function findOldestAgentMtime(runtime, { env = process.env, homedir = os.homedir
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith('gsd-')) continue;
-    const isAgentFile = ((runtime === 'opencode' || runtime === 'kilo') && entry.name.endsWith('.md'))
-      || (runtime === 'codex' && (entry.name.endsWith('.toml') || entry.name.endsWith('.md')));
+    const bakedExts = hostBehaviorsFor(runtime).bakedAgentFileExtensions;
+    const isAgentFile = Array.isArray(bakedExts) && bakedExts.some((ext) => entry.name.endsWith(ext));
     if (!isAgentFile) continue;
     try {
       const st = fsStatSync(path.join(dir, entry.name));
@@ -209,7 +193,7 @@ function warnIfStaleBake(cwd, options = {}) {
   } = options;
   try {
     const resolvedConfig = config || _readRuntimeConfig(cwd, { fsStatSync });
-    const runtime = resolveRuntimeFromConfig(resolvedConfig);
+    const runtime = resolveRuntimeFromConfig(resolvedConfig, env);
     if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return false;
 
     const dedupKey = `${runtime}::${path.resolve(cwd || '.')}`;

package/gsd-core/bin/lib/state-contract.cjs

@@ -73,6 +73,12 @@ exports.buildStateContract = buildStateContract;
 exports.publishStateContract = publishStateContract;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+// #5060: `phase-status.cjs` is a LOAD-TIME LEAF — no top-level requires of
+// its own (verification.cjs/plan-scan.cjs are required lazily, only inside
+// `phaseStatus()`) — so importing it here at top level does not reopen the
+// documented `state.cjs -> state-contract.cjs -> smart-entry.cjs -> state.cjs`
+// require cycle the file header warns about.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 // ─── Public wire vocabulary ────────────────────────────────────────────────
 exports.STATE_CONTRACT_VERSION = '1.0.0';
 exports.STATE_CONTRACT_FLAVOR = 'core';
@@ -80,12 +86,14 @@ exports.STATE_CONTRACT_FLAVOR = 'core';
 exports.CONTRACT_KEY_ORDER = Object.freeze(['contract', 'flavor', 'milestone', 'phases', 'next', 'updated_at']);
 /** Key order of each emitted phase object — an observable, pinned by test. */
 exports.PHASE_KEY_ORDER = Object.freeze(['number', 'name', 'status']);
-/** Frozen three-value phase status vocabulary. Conservative in what we send (Postel's Law). */
-exports.PHASE_STATUS = Object.freeze({
-    COMPLETE: 'complete',
-    IN_PROGRESS: 'in_progress',
-    PENDING: 'pending',
-});
+/**
+ * Frozen three-value phase status vocabulary. Conservative in what we send
+ * (Postel's Law). #5060: identity-pinned to the Phase Status Module's own
+ * `WIRE_STATUS` — this is not a copy, it IS that frozen object, so
+ * `state-contract`'s `PHASE_STATUS` and `phase-status.cjs`'s `WIRE_STATUS`
+ * can never independently drift.
+ */
+exports.PHASE_STATUS = phase_status_cjs_1.WIRE_STATUS;
 /** Frozen `publishStateContract` result reasons. */
 exports.PUBLISH_REASON = Object.freeze({
     PUBLISHED: 'published',
@@ -146,17 +154,6 @@ function buildMilestone(cwd) {
 }
 // ─── phases: Progress-table (primary) enumerator ───────────────────────────
 const PHASE_CELL_RE = /^(\d+(?:\.\d+)*)\s*[.:)–—-]?\s*(.*)$/;
-function statusFromProgressCell(raw) {
-    const normalized = (raw ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
-    if (normalized === 'complete')
-        return exports.PHASE_STATUS.COMPLETE;
-    if (normalized === 'in progress')
-        return exports.PHASE_STATUS.IN_PROGRESS;
-    // Everything else — 'not started', 'deferred' (design row 12, lossy by
-    // design), '', and any unrecognized word — folds to pending. An
-    // unrecognized status must never reach the wire as a 4th value.
-    return exports.PHASE_STATUS.PENDING;
-}
 function phasesFromProgressTable(table) {
     const { isSentinelPhaseId } = owners();
     const phases = [];
@@ -169,7 +166,7 @@ function phasesFromProgressTable(table) {
         const m = PHASE_CELL_RE.exec(cell);
         const number = m ? m[1] : cell;
         const name = m && m[2].trim().length > 0 ? m[2].trim() : null;
-        phases.push({ number, name, status: statusFromProgressCell(row['Status']) });
+        phases.push({ number, name, status: (0, phase_status_cjs_1.parseRoadmapStatusCell)(row['Status']) });
     }
     return phases;
 }