@opengsd/gsd-core 1.7.0 → 1.9.0

package/gsd-core/bin/lib/model-resolver.cjs

@@ -11,12 +11,17 @@
  * epic #1267; callers import resolvers from model-resolver.cjs directly.
  *
  * Dependencies (leaf modules only):
- *   - node:fs / node:path (stdlib, not currently needed — included for future use)
+ *   - node:fs / node:path (read the per-install .gsd-runtime marker + project config for the #2297 omit gate)
+ *   - ./runtime-name-policy.cjs (resolveRuntimeNameFromCandidates — canonicalize the active runtime)
+ *   - ./planning-workspace.cjs  (planningDir — workstream/project-aware project-config path)
  *   - ./config-loader.cjs    (loadConfig)
  *   - ./configuration.cjs    (CONFIG_DEFAULTS as CANONICAL_CONFIG_DEFAULTS)
  *   - ./model-profiles.cjs   (MODEL_PROFILES, AGENT_TO_PHASE_TYPE, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier)
- *   - ./model-catalog.cjs    (MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, PROVIDER_PRESETS)
+ *   - ./model-catalog.cjs    (MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, PROVIDER_PRESETS, VALID_TIERS)
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
 const { loadConfig } = configLoaderModule;
@@ -26,6 +31,92 @@ const configuration_cjs_1 = require("./configuration.cjs");
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES, AGENT_TO_PHASE_TYPE, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier } = modelProfiles;
 const model_catalog_cjs_1 = require("./model-catalog.cjs");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspaceMod;
+// ─── #2297: per-install runtime identity for the resolve_model_ids:"omit" gate ─
+//
+// The installer writes `resolve_model_ids:"omit"` into the SHARED
+// ~/.gsd/defaults.json for every runtime that lacks native model aliases (#1156).
+// Because that file is machine-wide, a non-Claude install would otherwise poison
+// a Claude no-project resolution into returning '' — silently defeating Claude's
+// adaptive tier aliases. The "omit" must therefore apply only when a runtime that
+// genuinely lacks native aliases is the one resolving.
+//
+// In a no-project session there is no `.planning/config.json` (so config.runtime
+// is null) and GSD_RUNTIME is not exported by gsd-core, so the only reliable
+// current-runtime signal is the per-install marker the installer co-locates next
+// to VERSION at <install>/gsd-core/.gsd-runtime (this file's dir is
+// <install>/gsd-core/bin/lib). Precedence for the gate: project config.runtime →
+// GSD_RUNTIME env (manual/CI override + test seam) → install marker → 'claude'.
+//
+// `claude` is currently the ONLY runtime with nativeModelAliases:true; a
+// registry-parity test guards this set so a future alias-capable runtime fails
+// loudly here instead of silently omitting.
+const RUNTIMES_WITH_NATIVE_ALIASES = new Set(['claude']);
+let _installMarkerCache;
+function readInstallRuntimeMarker() {
+    if (_installMarkerCache !== undefined)
+        return _installMarkerCache;
+    try {
+        const markerPath = node_path_1.default.join(__dirname, '..', '..', '.gsd-runtime');
+        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        _installMarkerCache = raw || null;
+    }
+    catch {
+        // No marker: dev/source tree, or an install predating #2297. Fall through to
+        // the 'claude' default (keeps tier aliases — never worse than the bug).
+        _installMarkerCache = null;
+    }
+    return _installMarkerCache;
+}
+// Test seams for the install-marker rung (the dev/source tree has no marker, so
+// the file read always bottoms out at 'claude' — these let tests exercise the
+// third precedence rung and reset the module-level cache between cases).
+function _setInstallRuntimeMarkerForTests(value) {
+    _installMarkerCache = value;
+}
+function _resetInstallRuntimeMarkerCacheForTests() {
+    _installMarkerCache = undefined;
+}
+// The runtime whose install is actually resolving, canonicalized so an alias or
+// case variant (e.g. "claude-code"/"Claude") cannot defeat the native-alias
+// check below (#2297 review). Precedence mirrors resolveRuntime()
+// (runtime-slash.cts): GSD_RUNTIME env → project config.runtime → per-install
+// .gsd-runtime marker → 'claude'.
+function resolveActiveRuntime(config) {
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], readInstallRuntimeMarker()) || 'claude';
+}
+// Did the PROJECT's own config (root `.planning/config.json` or the active
+// workstream/project override) explicitly set resolve_model_ids to "omit"?
+// Project config takes precedence over the shared ~/.gsd/defaults.json (#2297
+// out-of-scope guard + #2517 finding #4): an explicit project "omit" is honored
+// regardless of runtime, whereas an "omit" that came only from the global
+// defaults is ignored by native-alias runtimes. Workstream/project-scope aware
+// via planningDir (mirrors loadConfig's precedence: workstream value wins over
+// root); a plain read avoids loadConfig's normalization side effects.
+function projectExplicitlySetsOmit(cwd) {
+    const wsDir = planningDir(cwd);
+    const rootDir = node_path_1.default.join(cwd, '.planning');
+    const layers = wsDir === rootDir ? [rootDir] : [wsDir, rootDir]; // workstream > root
+    for (const dir of layers) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, 'config.json'), 'utf8'));
+            const value = parsed?.['resolve_model_ids'];
+            // First layer that sets the key wins (matches loadConfig's deep-merge
+            // precedence). A layer that omits the key falls through to the next.
+            if (value !== undefined)
+                return value === 'omit';
+        }
+        catch {
+            // Absent/unreadable layer — try the next.
+        }
+    }
+    return false;
+}
 /**
  * #2517 — Resolve the runtime-aware tier entry for (runtime, tier).
  */
@@ -209,8 +300,7 @@ function resolveModelInternal(cwd, agentType) {
     const phaseTypeTier = (phaseType && configModels && typeof configModels === 'object')
         ? configModels[phaseType]
         : undefined;
-    const VALID_TIERS = new Set(['opus', 'sonnet', 'haiku', 'inherit']);
-    const tier = (phaseTypeTier && VALID_TIERS.has(phaseTypeTier))
+    const tier = (phaseTypeTier && model_catalog_cjs_1.VALID_TIERS.has(phaseTypeTier))
         ? phaseTypeTier
         : (profile === 'inherit'
             ? 'inherit'
@@ -248,8 +338,18 @@ function resolveModelInternal(cwd, agentType) {
         if (entry?.model)
             return entry.model;
     }
-    // 4. resolve_model_ids: "omit"
-    if (config['resolve_model_ids'] === 'omit') {
+    // 4. resolve_model_ids: "omit" — runtime-aware (#2297). Honor "omit" when the
+    // PROJECT explicitly set it (user intent — project config wins, #2517 finding
+    // #4) OR when the active runtime genuinely lacks native model aliases. Only a
+    // native-alias runtime (Claude) ignores an "omit" that came solely from the
+    // SHARED ~/.gsd/defaults.json — the #2297 poisoning fix — and falls through to
+    // its tier aliases below. Active runtime: GSD_RUNTIME → config.runtime → the
+    // per-install .gsd-runtime marker → 'claude' (canonicalized).
+    // NOTE: a non-Claude runtime that HAS a populated runtime-tier map already
+    // returned its own model id at step 3 above, before this gate — for those the
+    // explicit-project-omit honoring here is moot (step 3 wins, by #2517 design).
+    if (config['resolve_model_ids'] === 'omit'
+        && (projectExplicitlySetsOmit(cwd) || !RUNTIMES_WITH_NATIVE_ALIASES.has(resolveActiveRuntime(config)))) {
         return '';
     }
     // 5. Profile lookup (Claude-native default).
@@ -262,7 +362,11 @@ function resolveModelInternal(cwd, agentType) {
     if (tier === 'inherit')
         return 'inherit';
     const alias = tier;
-    if (config['resolve_model_ids']) {
+    // Only the explicit `true` opt-in materializes full model IDs (#1569). Guard
+    // against the loose-truthy check catching a "omit" that a native-alias runtime
+    // ignored above (#2297): "omit" must fall through to the tier ALIAS here, not
+    // be materialized into a full ID Claude's Agent tool cannot spawn.
+    if (config['resolve_model_ids'] === true) {
         return model_catalog_cjs_1.MODEL_ALIAS_MAP[alias] || alias;
     }
     return alias;
@@ -353,6 +457,80 @@ function resolveModelForTier(cwd, agentType, attempt) {
     }
     return alias;
 }
+/**
+ * Keep only usable model ids: non-empty strings. A malformed config can put
+ * anything in here (nulls, numbers, blank strings), and a blank model id would
+ * resolve to an unusable agent invocation rather than failing visibly. Invalid
+ * entries are dropped and the surviving order is preserved, so the ladder stays
+ * predictable (ADR 227 — validate shape, not just type).
+ */
+function sanitizeProviderEscalation(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
+/**
+ * #2296 — Resolve the model for one attempt of the PROVIDER escalation ladder.
+ *
+ * The tier ladder (`resolveModelForTier`) escalates within one provider's
+ * `tier_models`, which does not help when that provider is the thing that is
+ * throttled. This walks `dynamic_routing.provider_escalation` instead: an
+ * ordered list of alternative model ids, capped by
+ * `min(max_escalations, list length)`.
+ *
+ * `applicable` is the caller's policy decision (only a quota-exceeded
+ * classification should consult this ladder). It is a parameter rather than a
+ * class check here so this module keeps depending only on leaf modules, per
+ * CONTEXT.md's Model Resolution module contract.
+ *
+ * Attempt 0 — and every non-applicable call — stays on the source model.
+ * `exhausted` reports that the ladder is spent so the caller can fail loudly
+ * naming every model it tried.
+ */
+function resolveProviderEscalation(cwd, agentType, attempt, applicable) {
+    // The model that would be used with no provider escalation at all.
+    const from = resolveModelForTier(cwd, agentType, 0);
+    const stay = (exhausted = false) => ({
+        from,
+        to: from,
+        escalated: false,
+        exhausted,
+        attempted: [from],
+        index: 0,
+    });
+    if (!applicable)
+        return stay();
+    const config = loadConfig(cwd);
+    const dr = config['dynamic_routing'];
+    if (!dr || typeof dr !== 'object' || dr['enabled'] !== true)
+        return stay();
+    if (dr['escalate_on_failure'] === false)
+        return stay();
+    const list = sanitizeProviderEscalation(dr['provider_escalation']);
+    if (list.length === 0)
+        return stay();
+    // Same default and same validity rule as the tier ladder above — a negative or
+    // non-integer max_escalations is invalid config, not a request for zero.
+    const maxEscalations = Number.isInteger(dr['max_escalations']) && dr['max_escalations'] >= 0
+        ? dr['max_escalations']
+        : 1;
+    const cap = Math.min(maxEscalations, list.length);
+    // An explicit cap of 0 means the ladder exists but is spent before it starts.
+    if (cap === 0)
+        return stay(true);
+    const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
+    if (attemptN === 0)
+        return stay();
+    const index = Math.min(attemptN, cap);
+    return {
+        from,
+        to: list[index - 1],
+        escalated: true,
+        exhausted: attemptN > cap,
+        attempted: [from, ...list.slice(0, index)],
+        index,
+    };
+}
 // ─── #443 — Unified effort + fast_mode resolvers ─────────────────────────────
 const VALID_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
 const EFFORT_SET = new Set(VALID_EFFORTS);
@@ -515,14 +693,18 @@ function resolveEffortForTier(cwd, agentType, attempt) {
 }
 module.exports = {
     resolveTierEntry,
+    CLAUDE_AGENT_ALIASES,
     resolveModelPolicy,
     resolveModelInternal,
     _resetModelPolicyWarningCacheForTests,
     _resetModelOverrideWarningCacheForTests,
+    _setInstallRuntimeMarkerForTests,
+    _resetInstallRuntimeMarkerCacheForTests,
     VALID_GRANULARITIES,
     resolveGranularityInternal,
     assertValidGranularityOverride,
     resolveModelForTier,
+    resolveProviderEscalation,
     VALID_EFFORTS,
     EFFORT_SET,
     nextEffort,

package/gsd-core/bin/lib/observability/logger.cjs

@@ -41,7 +41,12 @@ function _safeStringify(value) {
     }
 }
 /**
- * Determine whether the audit file should be written to.
+ * Determine whether observability is opt-in enabled — via the GSD_AUDIT env var
+ * or config.audit.enabled. Exported (#2620) so the live dispatch seam can decide
+ * whether to inject the reference logger at all: when observability is off we
+ * inject nothing (the Hub stays byte-for-byte silent, preserving the default
+ * dispatch output contract, incl. --json-errors); when on, the caller injects
+ * createDefaultLogger and gets the stderr-on-error line + opt-in file audit.
  */
 function _isAuditEnabled(config) {
     if (process.env['GSD_AUDIT'] === '1')
@@ -143,4 +148,4 @@ function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
         },
     };
 }
-module.exports = { createDefaultLogger, createNoOpLogger };
+module.exports = { createDefaultLogger, createNoOpLogger, isAuditEnabled: _isAuditEnabled };

package/gsd-core/bin/lib/onboard-projection.cjs

@@ -269,7 +269,9 @@ function buildOnboardProjection(cwd, options) {
             projectExists,
             mapReadiness: mapReadinessValue,
             onboardingSummaryExists,
-            onboardingSummaryPath: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
+            // #2376: absolute (anchored on cwd/project_root), not orchestrator-cwd-relative —
+            // a spawned subagent's own cwd may differ from the orchestrator's.
+            onboardingSummaryPath: toPosixPath(onboardingSummaryPath),
             hasPlanningArtifacts,
             missingPlanningFiles,
             handoffCommands,
@@ -289,13 +291,14 @@ function buildOnboardProjection(cwd, options) {
         doc_candidate_count: docCandidates.length,
         doc_candidates: docCandidates,
         onboarding_summary_exists: onboardingSummaryExists,
-        onboarding_summary_path: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
-        project_path: toPosixPath(node_path_1.default.relative(cwd, node_fs_1.default.existsSync(projectRootPath) ? projectRootPath : projectScopedPath)),
-        requirements_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md'))),
-        roadmap_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'))),
-        state_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'STATE.md'))),
-        codebase_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'codebase'))),
-        onboarding_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'onboarding'))),
+        // #2376: absolute — see comment on onboardingSummaryPath above.
+        onboarding_summary_path: toPosixPath(onboardingSummaryPath),
+        project_path: toPosixPath(node_fs_1.default.existsSync(projectRootPath) ? projectRootPath : projectScopedPath),
+        requirements_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md')),
+        roadmap_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
+        state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
+        codebase_dir: toPosixPath(node_path_1.default.join(planningRoot(cwd), 'codebase')),
+        onboarding_dir: toPosixPath(node_path_1.default.join(planningRoot(cwd), 'onboarding')),
     };
 }
 module.exports = {

package/gsd-core/bin/lib/phase-command-router.cjs

@@ -20,6 +20,12 @@ const command_aliases_cjs_1 = require("./command-aliases.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const commandRoutingHub = require("./command-routing-hub.cjs");
 const { createHub, ERROR_KINDS, makeInvalidArgs } = commandRoutingHub;
+// #2620 (ADR-0174 §6): inject the reference DispatchLogger on the live phase
+// dispatch path, but only when observability is opt-in enabled; otherwise the
+// Hub stays byte-for-byte silent via its no-op fallback.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const observabilityLogger = require("./observability/logger.cjs");
+const { createDefaultLogger, isAuditEnabled } = observabilityLogger;
 // ─── Implementation ───────────────────────────────────────────────────────────
 function routePhaseCommand({ phase, args, cwd, raw, error }) {
     // ── Unsupported subcommands ─────────────────────────────────────────────────
@@ -229,7 +235,10 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
     const manifest = { phase: manifestSubcommands };
     // ── Construct hub ──────────────────────────────────────────────────────────
     // #175: Hub is CJS-only — no mode param, no sdkLoader.
-    const hub = createHub({ cjsRegistry, manifest });
+    // #2620: wire the reference logger (ADR-0174 §6) only when observability is
+    // opt-in enabled; otherwise leave it unset so the Hub stays byte-for-byte
+    // silent via its no-op fallback.
+    const hub = createHub({ cjsRegistry, manifest, logger: isAuditEnabled() ? createDefaultLogger({ cwd }) : undefined });
     // ── Dispatch ────────────────────────────────────────────────────────────────
     const result = hub.dispatch({
         family: 'phase',