@opengsd/gsd-core 1.14.0 → 1.15.0

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

@@ -28,6 +28,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// #4717: runtime-identity fill — env rung + per-install marker rung.
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir, planningRoot } = planningWorkspace;
@@ -150,8 +153,21 @@ const CONFIG_DEFAULTS = {
     research_before_questions: _getNestedConfigDefault('workflow', 'research_before_questions'), // #3894
     smart_zone_tokens: _getNestedConfigDefault('workflow', 'smart_zone_tokens'),
     inline_plan_threshold: _getNestedConfigDefault('workflow', 'inline_plan_threshold'), // #3801
+    planner_stall_detection_enabled: _getNestedConfigDefault('planner', 'stall_detection_enabled'),
     max_prompt_tokens: _getNestedConfigDefault('review', 'max_prompt_tokens'),
 };
+/**
+ * Resolve the planner watchdog policy from hand-edited configuration.
+ * Only a real JSON boolean may override the default; strings/numbers/null
+ * fail safe to the manifest-owned default-on behavior (#4570).
+ */
+function resolvePlannerStallDetectionEnabled(value) {
+    if (typeof value === 'boolean')
+        return value;
+    // A missing or skewed manifest must never convert an absent override into
+    // permission to disable the watchdog. The documented contract is default-on.
+    return true;
+}
 /**
  * Deep-merge two plain config objects. `overlay` wins on key conflict.
  * Explicit `null` in overlay overrides base (null means "unset this key").
@@ -601,7 +617,7 @@ function _warnUnusableConfig(fault) {
  * cannot dirty the working tree; the ~30 callers that omit it keep persisting, so
  * a legacy config is still migrated exactly once by ordinary use.
  */
-function loadConfigResolved(cwd, options = {}) {
+function loadConfigResolvedInternal(cwd, options = {}) {
     // Opt-OUT, not opt-in: omitting the option must preserve the historical
     // write-back for every existing caller.
     const persist = options['persist'] !== false;
@@ -614,7 +630,7 @@ function loadConfigResolved(cwd, options = {}) {
         : (options['workstreamContext'] && Object.prototype.hasOwnProperty.call(options['workstreamContext'], 'ws'))
             ? options['workstreamContext']['ws']
             : (process.env['GSD_WORKSTREAM'] || null);
-    const ws = typeof activeWorkstream === 'string' ? activeWorkstream : (activeWorkstream === null ? null : null);
+    const ws = typeof activeWorkstream === 'string' ? activeWorkstream.trim() || null : null;
     // wsRequested: true when caller explicitly requested a non-empty workstream.
     // Used for source labeling (Fix 4) and early absent-dir intercept (Fix 2).
     const wsRequested = ws != null && ws !== '';
@@ -858,6 +874,7 @@ function loadConfigResolved(cwd, options = {}) {
             phase_naming: get('phase_naming') ?? defaults.phase_naming,
             project_code: get('project_code') ?? defaults.project_code,
             subagent_timeout: get('subagent_timeout', { section: 'workflow', field: 'subagent_timeout' }) ?? defaults.subagent_timeout,
+            planner_stall_detection_enabled: resolvePlannerStallDetectionEnabled(getNested('planner', 'stall_detection_enabled')),
             model_overrides: (parsed['model_overrides']) || null,
             agent_tools: (parsed['agent_tools']) || null,
             models: (parsed['models']) || null,
@@ -959,7 +976,7 @@ function loadConfigResolved(cwd, options = {}) {
         // `workstream: null` still wins the `hasOwnProperty` check at the top of this
         // function, so spreading cannot let `workstreamContext` reintroduce a workstream.
         if (wsRequested && rootParsed) {
-            const fb = loadConfigResolved(cwd, { ...options, workstream: null });
+            const fb = loadConfigResolvedInternal(cwd, { ...options, workstream: null });
             return fallback({ config: fb.config, source: 'root', degraded: true });
         }
         // Branch B, C, D, E
@@ -967,7 +984,7 @@ function loadConfigResolved(cwd, options = {}) {
             if (rootParsed) {
                 // Branch B: workstream requested but ws config.json absent; root config present.
                 // (Only reached when wsRequested is false — e.g. ws='' with .planning/workstreams//config.json)
-                const fb = loadConfigResolved(cwd, { ...options, workstream: null });
+                const fb = loadConfigResolvedInternal(cwd, { ...options, workstream: null });
                 return fallback({ config: fb.config, source: 'root', degraded: true });
             }
             // Branch C: .planning/ exists but no config.json and no root config — federated/builtin defaults
@@ -1016,6 +1033,7 @@ function loadConfigResolved(cwd, options = {}) {
                 resolve_model_ids: (globalDefaults['resolve_model_ids']) ?? defaults.resolve_model_ids,
                 context_window: (globalDefaults['context_window']) ?? defaults.context_window,
                 subagent_timeout: (globalDefaults['subagent_timeout']) ?? defaults.subagent_timeout,
+                planner_stall_detection_enabled: resolvePlannerStallDetectionEnabled(globalDefaults['planner']?.['stall_detection_enabled']),
                 model_overrides: (globalDefaults['model_overrides']) || null,
                 models: (globalDefaults['models']) || null,
                 granularity: (globalDefaults['granularity']) !== undefined ? globalDefaults['granularity'] : null,
@@ -1054,6 +1072,48 @@ function loadConfigResolved(cwd, options = {}) {
         }
     }
 }
+/**
+ * #4717 — fill an empty `runtime` from the environment, then the per-install
+ * marker. writeNonClaudeDefaults stamps `runtime` into the SHARED
+ * ~/.gsd/defaults.json with whichever non-Claude runtime installed first, so
+ * direct readers of config.runtime saw another runtime's identity (or
+ * nothing) on a multi-runtime machine. Copy-on-write: the builtin-defaults
+ * branch returns a shared object, so never assign into it. An explicit
+ * config.runtime is never overridden.
+ */
+function fillRuntimeIdentity(resolved) {
+    const cfg = resolved?.config;
+    if (!cfg)
+        return resolved;
+    const runtime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], (0, runtime_slash_cjs_1.readInstallRuntimeMarker)());
+    // Only a runtime the name policy can canonicalize is an identity. Unknown
+    // tokens pass THROUGH resolveRuntimeNameFromCandidates (future-runtime
+    // tolerance) and must not be materialized into config.runtime, where ~30
+    // consumers would read them — fail safe to no identity (#4717 review).
+    const canonicalRuntime = runtime ? (0, runtime_name_policy_cjs_1.canonicalizeRuntimeName)(runtime) : null;
+    if (!canonicalRuntime)
+        return resolved;
+    // Rung 1 — empty runtime: materialize THIS install's identity (env, then
+    // the per-install marker). An explicit runtime is never overridden.
+    if (!cfg['runtime']) {
+        return { ...resolved, config: { ...cfg, runtime: canonicalRuntime } };
+    }
+    // Rung 2 (#4717 stamped-defaults leg): the global-defaults branch forwards
+    // the SHARED ~/.gsd/defaults.json's runtime verbatim — whichever non-Claude
+    // runtime installed FIRST stamped that machine-wide file, and every other
+    // runtime's resolution inherited its identity (the issue's second failure
+    // shape). When THIS install carries its own identity (GSD_RUNTIME or the
+    // marker), the stamp — not the operator — is speaking: correct it. Project
+    // and workstream configs are explicit operator intent and are never touched;
+    // with no install identity of its own the stamped value stays (status quo).
+    if (resolved.source === 'global-defaults') {
+        return { ...resolved, config: { ...cfg, runtime: canonicalRuntime } };
+    }
+    return resolved;
+}
+function loadConfigResolved(cwd, options = {}) {
+    return fillRuntimeIdentity(loadConfigResolvedInternal(cwd, options));
+}
 /**
  * loadConfig — backwards-compatible config loading, now a thin wrapper over loadConfigResolved.
  * Returns the config object only; for provenance metadata use loadConfigResolved.
@@ -1072,6 +1132,7 @@ module.exports = {
     _getNestedConfigDefault,
     _getConfigValue,
     _getConfigNested,
+    resolvePlannerStallDetectionEnabled,
     _deepMergeConfig,
     _warnedUnknownConfigKeys,
     _warnedShadowedGlobalKeys,

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

@@ -20,11 +20,11 @@ const cliExitMod = require("./cli-exit.cjs");
 const { ExitError } = cliExitMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoader = require("./config-loader.cjs");
-const { CONFIG_DEFAULTS } = configLoader;
+const { CONFIG_DEFAULTS, resolvePlannerStallDetectionEnabled } = configLoader;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir, planningRoot, withPlanningLock } = planningWorkspace;
+const { planningDir, planningRoot, resolveEnvWorkstream, withPlanningLock } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const modelProfiles = require("./model-profiles.cjs");
 const { VALID_PROFILES, getAgentToModelMapForProfile, formatAgentToModelMapAsTable } = modelProfiles;
@@ -66,6 +66,14 @@ const SHIP_PR_BODY_TEMPLATE_TOKENS = new Set([
     'padded_phase',
 ]);
 const SHIP_PR_BODY_SOURCE_RE = /^(ROADMAP|PLAN|SUMMARY|VERIFICATION|STATE|REQUIREMENTS|CONTEXT)\.md\s+##\s+[^\r\n#][^\r\n]*$/;
+// ADR-612 PR-5: configuration accepts every convention the runtime can read.
+// Keep this distinct from roadmap-upgrade's supported target set: sequential
+// is valid project configuration but is not a migration destination.
+const VALID_PHASE_ID_CONVENTIONS = Object.freeze([
+    'sequential',
+    'milestone-prefixed',
+    'bracket',
+]);
 /**
  * Schema-level defaults for well-known config keys.
  * When a key is absent from config.json and no --default flag was supplied,
@@ -75,6 +83,7 @@ const SCHEMA_DEFAULTS = {
     'context_window': 200000,
     'executor.stall_detect_interval_minutes': 5,
     'executor.stall_threshold_minutes': 10,
+    'planner.stall_detection_enabled': CONFIG_DEFAULTS.planner_stall_detection_enabled,
     'planner.stall_detect_interval_minutes': 5,
     'planner.stall_threshold_minutes': 10,
     'git.create_tag': true,
@@ -152,12 +161,15 @@ function resolveSchemaDefault(cwd, kp) {
  * Centralizing emission here means masking can't be missed at a call site.
  */
 function emitResolvedDefault(kp, value, raw) {
+    const resolvedValue = kp === 'planner.stall_detection_enabled'
+        ? resolvePlannerStallDetectionEnabled(value)
+        : value;
     if ((0, secrets_cjs_1.isSecretKey)(kp)) {
-        const masked = (0, secrets_cjs_1.maskSecret)(value);
+        const masked = (0, secrets_cjs_1.maskSecret)(resolvedValue);
         output(masked, raw, masked);
         return;
     }
-    output(value, raw, String(value));
+    output(resolvedValue, raw, String(resolvedValue));
 }
 // ─── Validation helpers ───────────────────────────────────────────────────────
 function validateKnownConfigKeyPath(keyPath) {
@@ -542,7 +554,7 @@ function _setNestedValue(config, keyPath, parsedValue) {
 }
 /**
  * Deletes a value from the config object, allowing nested values via dot
- * notation (e.g., "review.models.gemini"). Mirrors `_setNestedValue`'s
+ * notation (e.g., "review.models.codex"). Mirrors `_setNestedValue`'s
  * prototype-pollution guard on every path segment (including intermediates).
  *
  * Unlike `_setNestedValue`, this NEVER creates missing intermediate objects —
@@ -806,6 +818,9 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
     const VALID_CONTEXT_VALUES = ['dev', 'research', 'review'];
     if (kp === 'context')
         assertEnumValue(parsedValue, val, VALID_CONTEXT_VALUES, 'context value');
+    if (kp === 'phase_id_convention') {
+        assertEnumValue(parsedValue, val, VALID_PHASE_ID_CONVENTIONS, 'phase_id_convention');
+    }
     // Codebase drift detector (#2003)
     const VALID_DRIFT_ACTIONS = ['warn', 'auto-remap'];
     if (kp === 'workflow.drift_action')
@@ -853,6 +868,13 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
             error(`Invalid workflow.agent_hint_routing '${val}'. Must be a boolean (true or false).`);
         }
     }
+    // Planner watchdog opt-out (#4570) — only a real boolean may change the
+    // default-on policy. In particular, string "false" must not disable it.
+    if (kp === 'planner.stall_detection_enabled') {
+        if (typeof parsedValue !== 'boolean') {
+            error(`Invalid planner.stall_detection_enabled '${val}'. Must be a boolean (true or false).`);
+        }
+    }
     // #3086 — git.create_tag: boolean only
     if (kp === 'git.create_tag') {
         if (typeof parsedValue !== 'boolean') {
@@ -1161,6 +1183,9 @@ function cmdConfigGet(cwd, keyPath, raw, defaultValue) {
         }
         error(`Key not found: ${kp}`, ERROR_REASON.CONFIG_KEY_NOT_FOUND);
     }
+    if (kp === 'planner.stall_detection_enabled') {
+        current = resolvePlannerStallDetectionEnabled(current);
+    }
     // Never echo plaintext for sensitive keys via config-get. Plaintext lives
     // in config.json on disk; the CLI surface always shows the masked form.
     if ((0, secrets_cjs_1.isSecretKey)(kp)) {
@@ -1190,7 +1215,7 @@ function resolveFromRootConfig(cwd, kp) {
     // diverges from planningRoot without a workstream and loadConfigResolved does NOT
     // inherit root — matching the runtime's own `if (ws)` gate keeps the two surfaces
     // from diverging on the project-scoped (non-workstream) case.
-    if (!process.env['GSD_WORKSTREAM'])
+    if (!resolveEnvWorkstream())
         return { found: false, value: undefined };
     const root = planningRoot(cwd);
     const rootConfigPath = node_path_1.default.join(root, 'config.json');
@@ -1297,7 +1322,7 @@ function cmdConfigPath(cwd, _raw, workstreamContext = null) {
  * (caller uses `await` which is safe on a sync return value).
  */
 function cmdMigrateConfig(cwd, raw) {
-    const ws = process.env['GSD_WORKSTREAM'] || null;
+    const ws = resolveEnvWorkstream();
     // #3749: resolve the migration target through the project-aware resolver so
     // GSD_PROJECT scopes the write; migrateOnDisk itself cannot (see its
     // configPathOverride note).
@@ -1345,6 +1370,7 @@ function cmdMigrateConfig(cwd, raw) {
 }
 module.exports = {
     VALID_CONFIG_KEYS,
+    VALID_PHASE_ID_CONVENTIONS,
     cmdConfigEnsureSection,
     cmdConfigSet,
     cmdConfigGet,

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

@@ -85,14 +85,14 @@ const DECISION_ID_SOURCE = 'D[0-9]*-[A-Za-z0-9][A-Za-z0-9_-]*';
 const ID_ATTEMPT_SOURCE = 'D(?:[0-9][A-Za-z0-9]*)?-';
 /**
  * Colon form: `- **D[phase]-NN[ [tags]]:** text`
- * (#1343: `[^:*]*` subsumes any pre-colon prose, stops at `:**`)
+ * (#1343: the pre-colon run subsumes any pre-colon prose, stops at `:**`; #4788: the run is code-span-aware — a backticked span is consumed whole, so a `:` or `*` INSIDE it is data, never grammar)
  * Group 1 captures the FULL id including any phase prefix (#4130).
  * The ID is consumed atomically `(?=(…))\1` — see the hardening note above
  * the constants (#4130 follow-up); with the tail unable to give back, the
  * remaining `[^:*]*:` scan has a single viable split and the whole match is
  * linear in line length.
  */
-const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^:*]*:\\*\\*\\s*(.*)$`);
+const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|[^:*\\u0060])*:\\*\\*\\s*(.*)$`);
 /**
  * Em-dash form: `- **D[phase]-NN[ [tags]] — title** body`
  * The em-dash (U+2014) or its lookalike separates the ID+tags group from a title
@@ -112,22 +112,32 @@ const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1
  * candidate and `**` succeeds or fails identically; no capture involves the
  * dash position. The ID is atomic like the other forms (driver #1).
  */
-const bulletEmDashRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^*—–]*[—–][^*]*\\*\\*\\s*(.*)$`);
+const bulletEmDashRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|[^*—–\\u0060])*[—–](?:\\u0060[^\\u0060]*\\u0060|[^*\\u0060])*\\*\\*\\s*(.*)$`);
 /**
  * Titled-colon form: `- **D[phase]-NN[ [tags]]: Title.** body`
  * A title sits between the colon and the closing `**` (so the `:**` anchor of
  * bulletColonRe fails, and there is no em-dash for bulletEmDashRe). This is a strict
  * superset of the colon-immediate form, so it MUST be checked AFTER bulletColonRe and
- * bulletEmDashRe — it only catches bullets those two miss. The title run is `[^:*]*` (no
- * colon, no `*`) so a genuinely-malformed bullet with a colon in the pre-separator run
- * (e.g. `D-07 ratio 3:1:**`) still fails the anchor and falls through to the parse-miss
- * guard — matching bulletColonRe's `[^:*]*` discipline that the separator colon is the
- * only colon permitted before `**`. (#1639)
+ * bulletEmDashRe — it only catches bullets those two miss. The title runs are code-span-aware
+ * (#4788) but still exclude `*`, so a genuinely-malformed bullet with no bare colon at all
+ * before `**` still fails the anchor and falls through to the parse-miss guard — the #1639
+ * fail-loud discipline: the separator must be a BARE colon before `**`. A code span's
+ * `:`/`*` is data, never grammar; an UNTERMINATED backtick now fails loud (previously it was
+ * an ordinary character) — the deliberate cost of span opacity.
+ *
+ * #4793/#4958: the pre-separator run tolerates a bare colon as prose ONLY when it is
+ * immediately followed by whitespace (`:(?=\s)`), e.g. a natural sentence colon in
+ * `D-02: Two managers … same pair: the second is rejected.`. A colon with no following
+ * whitespace (a compact/ratio-style colon like `3:1`) is never consumed by this branch, so
+ * it still hard-caps the pre-separator run and the #1639/#4130/#1343 negative-space fixtures
+ * (e.g. `D-07 ratio 3:1:**`) still fail loud. The post-separator branch is unchanged and
+ * still excludes colons, so normal greedy backtracking selects the LAST valid split (a bare
+ * colon followed by whitespace, or the anchor colon itself) before the closing `**`.
  *
  * The ID is consumed atomically `(?=(…))\1` like the other forms — the
  * hardening note above the constants explains why (#4130 follow-up).
  */
-const bulletTitledColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^:*]*:[^:*]*\\*\\*\\s*(.*)$`);
+const bulletTitledColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|:(?=\\s)|[^:*\\u0060])*:(?:\\u0060[^\\u0060]*\\u0060|[^:*\\u0060])*\\*\\*\\s*(.*)$`);
 /**
  * #4130: the parse-miss guard's probe — a line whose bold lead-in ATTEMPTS the
  * ID grammar (see `ID_ATTEMPT_SOURCE`) but failed all three bullet patterns
@@ -403,6 +413,7 @@ function parseDecisionLines(block) {
     let current = null;
     let openIndent = null;
     let parseMisses = 0;
+    const unreadableIds = [];
     const flush = () => {
         if (current) {
             current.text = current.text.trim();
@@ -501,6 +512,11 @@ function parseDecisionLines(block) {
         if (parseMissGuardRe.test(line)) {
             flush();
             parseMisses += 1;
+            // #4794: carry the attempted id so a caller capturing stdout (a JSON gate)
+            // can name the decision to fix — today it exists only in this stderr warn.
+            const attempted = line.match(/\*\*\s*(D(?:[0-9][A-Za-z0-9]*)?-[A-Za-z0-9_-]*)/);
+            if (attempted && !unreadableIds.includes(attempted[1]))
+                unreadableIds.push(attempted[1]);
             console.warn(`parseDecisions: ignored unparseable decision bullet: ${trimmed}`);
             continue;
         }
@@ -516,7 +532,7 @@ function parseDecisionLines(block) {
         }
     }
     flush();
-    return { decisions: out, parseMisses };
+    return { decisions: out, parseMisses, unreadableIds };
 }
 // ─── Primary entry point: extractDecisions ────────────────────────────────────
 /**
@@ -541,13 +557,13 @@ function extractDecisions(content) {
     const taggedBlocks = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(stripped, 'decisions');
     if (taggedBlocks.length > 0) {
         const combined = taggedBlocks.join('\n\n');
-        const { decisions, parseMisses } = parseDecisionLines(combined);
+        const { decisions, parseMisses, unreadableIds } = parseDecisionLines(combined);
         if (decisions.length > 0 && parseMisses === 0) {
             return { decisions, outcome: 'parsed' };
         }
         // FIX B: parse-misses present — could-not-parse even if some decisions extracted.
         if (parseMisses > 0) {
-            return { decisions, outcome: 'could-not-parse' };
+            return { decisions, outcome: 'could-not-parse', unreadableIds };
         }
         // FIX A: Block present but 0 extracted and no parse-misses.
         // Only report could-not-parse when there is genuine evidence of real decisions
@@ -568,13 +584,13 @@ function extractDecisions(content) {
     // stripFences:true → inner fences inside the section body are stripped.
     const section = (0, markdown_sectionizer_cjs_1.collectSection)(content, (h) => /decisions?\b/i.test(h.text), { levelBounded: true, stripFences: true });
     if (section !== null) {
-        const { decisions, parseMisses } = parseDecisionLines(section.body);
+        const { decisions, parseMisses, unreadableIds } = parseDecisionLines(section.body);
         if (decisions.length > 0 && parseMisses === 0) {
             return { decisions, outcome: 'parsed' };
         }
         // FIX B: parse-misses present — could-not-parse even if some decisions extracted.
         if (parseMisses > 0) {
-            return { decisions, outcome: 'could-not-parse' };
+            return { decisions, outcome: 'could-not-parse', unreadableIds };
         }
         // FIX A: Heading found but 0 extracted and no parse-misses.
         // Report could-not-parse when the section body holds a decision-entry-shaped

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

@@ -1394,6 +1394,14 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) {
     // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
     // per file rather than per content digest (#1882, ADR-1411 wiring clause).
     const fm = extractFrontmatter(content, fullPath);
+    // #4806: an unparseable frontmatter block is a distinct outcome — the file
+    // HAS a frontmatter block but its YAML failed to parse. Reporting
+    // "Field not found" tells the caller the key is absent, which is
+    // indistinguishable from a file that genuinely lacks it.
+    if (fm[FRONTMATTER_UNPARSEABLE] === true) {
+        output({ error: 'Frontmatter is not parseable YAML — fix the syntax error in the frontmatter block', path: filePath }, raw, undefined);
+        return;
+    }
     if (field) {
         const value = fm[field];
         if (value === undefined) {
@@ -1649,4 +1657,9 @@ module.exports = {
     cmdFrontmatterMerge,
     cmdFrontmatterValidate,
     propagateCommentChannel,
+    // #4917 / ADR-4910 Decision 1: additive-only export so `planning-document.cts`
+    // can COMPOSE this seam's fence-detection grammar (byte-0 rule, BOM strip,
+    // CR handling) instead of reimplementing it. No behavior change — same
+    // function `extractFrontmatter`/`frontmatterListEntries` already call.
+    frontmatterRegion,
 };

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

@@ -445,14 +445,17 @@ function graphifyStatus(cwd) {
         return disabledResponse();
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { exists: false, message: configured
+        return { exists: false, graph_path: graphPath, message: configured
                 ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
                 : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);
     const graph = safeReadJson(graphPath);
     if (!graph) {
-        return { error: 'Failed to parse graph.json' };
+        // Still surface graph_path (#4836 Minor 1): callers gate on `exists`, not
+        // on this outcome, so without it they'd fall through to the CLI-first
+        // branch with no --graph value to substitute for the <graph> placeholder.
+        return { error: 'Failed to parse graph.json', graph_path: graphPath };
     }
     const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
     const age = Date.now() - stat.mtimeMs;
@@ -482,6 +485,11 @@ function graphifyStatus(cwd) {
         (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
     return {
         exists: true,
+        // The absolute location the whole graphify surface reads, already resolved
+        // through `graphify.graph_path` (#1825). Callers that shell out to the
+        // graphify CLI pass this as `--graph` so the umbrella override is honoured
+        // there too, instead of re-deriving `.planning/graphs/graph.json` (#4836).
+        graph_path: graphPath,
         last_build: stat.mtime.toISOString(),
         node_count: (graph.nodes || []).length,
         edge_count: (graph.edges || graph.links || []).length,

package/gsd-core/bin/lib/host-runtime-detection.cjs

@@ -24,6 +24,7 @@ exports.resolveReportedRuntime = resolveReportedRuntime;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 const update_context_cjs_1 = require("./update-context.cjs");
 Object.defineProperty(exports, "CODEX_CONFIG_MARKER", { enumerable: true, get: function () { return update_context_cjs_1.CODEX_CONFIG_MARKER; } });
 // Codex sandbox env vars set by the shell tool / Seatbelt child-process spawn.
@@ -127,6 +128,14 @@ function resolveReportedRuntimeUnsafe(projectDir, deps) {
     const explicit = (0, runtime_slash_cjs_1.resolveExplicitRuntime)(projectDir, deps?.env ?? process.env);
     if (explicit)
         return explicit;
+    // #4717: the per-install marker names the runtime that owns THIS tree — a
+    // stronger signal than host sniffing, which misreports every session on a
+    // multi-runtime machine (e.g. a globally exported CODEX_HOME makes a Claude
+    // Code session read as codex). Marker-less trees (dev/source, pre-#2297
+    // installs) fall through to host detection unchanged.
+    const marker = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)((0, runtime_slash_cjs_1.readInstallRuntimeMarker)());
+    if (marker)
+        return marker;
     const detected = detectHostRuntime(deps);
     if (detected.runtime)
         return detected.runtime;