@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -10,12 +10,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_ARGV = exports.EFFORT_RENDERING = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
+exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_ARGV = exports.EFFORT_RENDERING = exports.CLAUDE_AGENT_ALIASES = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
+exports.isAnthropicFlavoredModel = isAnthropicFlavoredModel;
 exports.nextTier = nextTier;
 exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
 exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
 exports.renderEffortArgv = renderEffortArgv;
 exports.renderEffortForRuntime = renderEffortForRuntime;
+exports.mergeEffortTierDefaults = mergeEffortTierDefaults;
 const node_path_1 = __importDefault(require("node:path"));
 // In .cts (CommonJS output) files, `require` is available as a global;
 // we use it directly to load JSON candidates.
@@ -103,6 +105,27 @@ exports.PROVIDER_PRESETS = _catalog.providerPresets ?? {};
 exports.KNOWN_PROVIDERS = new Set(Object.entries(exports.PROVIDER_PRESETS)
     .filter(([, tiers]) => Object.values(tiers).some((budgets) => budgets && Object.values(budgets).some((entry) => entry && entry.model)))
     .map(([name]) => name));
+// ─── #3241 — Anthropic-flavored model detection ──────────────────────────────
+//
+// Moved here from src/model-resolver.cts (the "seam decision" in
+// .gsd/phase/feat-3241-codex-omit-model-by-default/40-design.md): this leaf
+// module is the one common dependency both model-resolver and the (layering-
+// restricted) install-time Codex-posture checks can share without pulling
+// model-resolver's config-loader dependency chain into a "pure read/verify"
+// caller. model-resolver re-exports both names for back-compat.
+//
+// #2310 — True if `model` is an Anthropic-flavored value that must never appear as a
+// Codex agent `.toml` `model`. Two forms: (a) a bare Claude Agent-tool tier alias
+// (opus/sonnet/haiku/fable — CLAUDE_AGENT_ALIASES below); (b) any Claude model id in
+// any provider namespacing — `claude-*`, `anthropic/claude-*`, `us.anthropic.claude-*`
+// (the forms the catalog assigns to opencode/hermes/kilo, reachable on a Codex .toml
+// via the runtime-resolver path). No OpenAI/Codex model id contains "claude", so a
+// case-insensitive substring test is a safe, exhaustive guard for (b). Codex/ChatGPT
+// rejects all of these.
+exports.CLAUDE_AGENT_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
+function isAnthropicFlavoredModel(model) {
+    return typeof model === 'string' && (exports.CLAUDE_AGENT_ALIASES.has(model) || model.toLowerCase().includes('claude'));
+}
 function nextTier(currentTier) {
     const order = ['light', 'standard', 'heavy'];
     const idx = order.indexOf(String(currentTier));
@@ -205,6 +228,13 @@ function renderEffortArgv(host, universalEffort, effortSurface) {
  * Render a universal effort string for a specific runtime.
  */
 function renderEffortForRuntime(runtime, universalEffort) {
+    // #3533 (10d): 'inherit' is not a wire level on ANY runtime — it means
+    // "omit the key / pass no argument and follow the session/host default".
+    // Renderers must never emit it as a literal; null param/channel tells
+    // resolve-execution consumers there is no propagation.
+    if (universalEffort === 'inherit') {
+        return { value: 'inherit', param: null, channel: null };
+    }
     const spec = exports.EFFORT_RENDERING[runtime];
     if (!spec) {
         return { value: universalEffort, param: null, channel: null };
@@ -215,5 +245,33 @@ function renderEffortForRuntime(runtime, universalEffort) {
         channel: spec.channel,
     };
 }
+/**
+ * #3531 (10c) — Merge a config `effort.routing_tier_defaults` block over the
+ * manifest tier defaults instead of replacing them. A partial config must not
+ * discard built-ins: per tier, a valid override value wins and an invalid one
+ * is ignored so the manifest value for that tier surfaces (ADR-443 D1's
+ * "invalid values fall through" holds within the merged layer).
+ *
+ * Pure: returns a new object and never mutates either input — the manifest
+ * constants (`CANONICAL_CONFIG_DEFAULTS`, the catalog cache) stay frozen. The
+ * validator is injected because `EFFORT_SET` lives in model-resolver, which
+ * imports this leaf (a reverse import would be a cycle); both effort
+ * resolvers pass their own `(v) => typeof v === 'string' && EFFORT_SET.has(v)`.
+ */
+function mergeEffortTierDefaults(manifest, override, isValid) {
+    const merged = { ...(manifest || {}) };
+    if (override && typeof override === 'object' && !Array.isArray(override)) {
+        for (const [tier, value] of Object.entries(override)) {
+            // House pollution guard (mirrors _deepMergeConfig in config-loader): the
+            // string-only validator already makes these inert, but an explicit skip
+            // keeps this merge safe even if a caller's validator is ever relaxed.
+            if (tier === '__proto__' || tier === 'constructor' || tier === 'prototype')
+                continue;
+            if (isValid(value))
+                merged[tier] = value;
+        }
+    }
+    return merged;
+}
 // ─── Fast mode propagation ───────────────────────────────────────────────────
 exports.RUNTIMES_WITH_FAST_MODE = new Set(['api']);

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

@@ -17,7 +17,8 @@
  *   - ./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, VALID_TIERS)
+ *   - ./model-catalog.cjs    (MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, PROVIDER_PRESETS, VALID_TIERS,
+ *                             CLAUDE_AGENT_ALIASES — re-exported below for back-compat, #3241)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -153,7 +154,9 @@ const CLAUDE_POLICY_ID_TO_ALIAS = {
         .map(([aliasName, id]) => [id, aliasName])),
     'claude-fable-5': 'fable',
 };
-const CLAUDE_AGENT_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
+// CLAUDE_AGENT_ALIASES moved to ./model-catalog.cts (#3241) — imported above
+// and re-exported below for back-compat (bin/install.js:474,
+// tests/codex-config.test.cjs:24 depend on the name being on this module).
 // Dedupe stderr warnings so repeated agent resolutions don't spam (#1133).
 const _modelPolicyUnmappableWarned = new Set();
 function warnModelPolicyUnmappable(agentType, policyModel, tier) {
@@ -216,7 +219,7 @@ function mapClaudeOverrideForRuntime(override, configRuntime, agentType) {
     if (Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, override)) {
         return CLAUDE_POLICY_ID_TO_ALIAS[override];
     }
-    if (CLAUDE_AGENT_ALIASES.has(override))
+    if (model_catalog_cjs_1.CLAUDE_AGENT_ALIASES.has(override))
         return override;
     if (override.startsWith('claude-')) {
         warnModelOverrideUnmappable(agentType, override);
@@ -278,33 +281,161 @@ function resolveModelPolicy(policy, tier) {
         return null;
     return budgetEntry.model;
 }
+/**
+ * #2229 — the profile/phase-type tier for (config, agentType).
+ *
+ * Extracted verbatim from resolveModelInternal's step 2 so the same expression can
+ * answer "which tier did GSD resolve?" without also resolving a model id. The
+ * extraction is behaviour-preserving by construction: resolveModelInternal calls
+ * straight back into it.
+ *
+ * Returns null when the agent has no catalog entry and the profile is not `inherit`.
+ */
+function computeProfileTier(config, agentType) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const profile = String(config['model_profile'] || 'balanced').toLowerCase();
+    // Own-property guard: agentType is an unvalidated CLI positional (the
+    // `resolve-model <agent-type>` argument is never checked against a known
+    // agent list), so a prototype-chain agentType ("toString", "constructor")
+    // would otherwise return an inherited member from this plain object
+    // instead of undefined — verified reachable purely via the CLI.
+    const modelProfilesMap = MODEL_PROFILES;
+    const agentModels = Object.hasOwn(modelProfilesMap, agentType) ? modelProfilesMap[agentType] : undefined;
+    const phaseType = (AGENT_TO_PHASE_TYPE)[agentType];
+    const configModels = config['models'];
+    const phaseTypeTier = (phaseType && configModels && typeof configModels === 'object')
+        ? configModels[phaseType]
+        : undefined;
+    return (phaseTypeTier && model_catalog_cjs_1.VALID_TIERS.has(phaseTypeTier))
+        ? phaseTypeTier
+        : (profile === 'inherit'
+            ? 'inherit'
+            : (agentModels
+                // Own-property guard: `profile` is a config-supplied string
+                // (config['model_profile'], lower-cased); an already-lowercase
+                // prototype-chain key ("constructor", "__proto__") would otherwise
+                // return an inherited non-string member instead of falling back to
+                // 'balanced' (verified: profile:"constructor"/"__proto__" leaked a
+                // function/object through both the tier and model resolution paths).
+                ? ((Object.hasOwn(agentModels, profile) ? agentModels[profile] : undefined) || agentModels['balanced'])
+                : null));
+}
+/**
+ * #2229 — the effective model TIER for (config, agentType), as a signal a workflow can
+ * read: `gsd_run query resolve-model <agent> --pick tier`.
+ *
+ * Why this is not just "look at the resolved model": on every runtime the installer
+ * configures with `resolve_model_ids: "omit"` — which is every non-Claude runtime, see
+ * docs/CONFIGURATION.md — resolveModelInternal deliberately returns '' below. A guard
+ * keyed on the model id therefore cannot tell a budget-tier run from a top-tier one
+ * there, while the tier itself is computed ABOVE that early-return and stays knowable.
+ *
+ * Honesty contract — this never guesses, because a guard that reports a wrong tier is
+ * worse than one that reports none:
+ *   - a per-agent `model_overrides` pin naming a known alias (or a full Claude id that
+ *     maps to one) reports that alias;
+ *   - a pin that maps to nothing reports 'unknown' — a raw model id carries no tier;
+ *   - `model_profile: inherit` reports 'inherit' — the session model is not ours to name;
+ *   - an agent with no catalog entry reports 'unknown'.
+ *
+ * Callers must treat 'unknown' and 'inherit' as "cannot tell", never as "adequate".
+ */
+function resolveTierFromConfig(config, agentType) {
+    const rawOverrides = config['model_overrides'];
+    const modelOverrides = (rawOverrides && typeof rawOverrides === 'object' && !Array.isArray(rawOverrides))
+        ? rawOverrides
+        : null;
+    // Own-property guard: agentType is a caller-supplied string (the
+    // `resolve-model <agent-type>` CLI positional is not validated against a
+    // known agent list); a prototype-chain agentType ("toString",
+    // "constructor") against ANY model_overrides object — even `{}` — would
+    // otherwise return an inherited member instead of undefined.
+    const override = (modelOverrides && Object.hasOwn(modelOverrides, agentType))
+        ? modelOverrides[agentType]
+        : undefined;
+    if (override && typeof override === 'string') {
+        if (model_catalog_cjs_1.CLAUDE_AGENT_ALIASES.has(override))
+            return override;
+        // Own-property guard: this indexes a plain object with a config-supplied
+        // string, so a prototype-chain key ("toString", "constructor", "valueOf")
+        // would otherwise return an inherited member instead of undefined — and a
+        // function-valued tier is dropped entirely by JSON.stringify, silently
+        // removing the key a guard depends on.
+        const alias = Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, override)
+            ? CLAUDE_POLICY_ID_TO_ALIAS[override]
+            : undefined;
+        if (typeof alias === 'string' && alias)
+            return alias;
+        return 'unknown';
+    }
+    const profileTier = computeProfileTier(config, agentType);
+    // #3282 — mirror resolveModelInternal's step 2.5 (model_policy preset). The
+    // profile tier alone under-reports: model_policy can dispatch a DIFFERENT
+    // tier than the profile implies (e.g. a `balanced` profile's "sonnet" tier
+    // combined with `model_policy: {budget: 'low'}` actually spawns "haiku"),
+    // and reporting the profile tier there is exactly the under-report this
+    // fixes — a haiku-tier run must never be reported as "sonnet". Skipped
+    // under the same condition resolveModelInternal skips it (no tier, or
+    // "inherit" — the session model is not ours to name).
+    if (profileTier && profileTier !== 'inherit') {
+        const mergedPolicy = config['model_policy']
+            ? { ...config['model_policy'], runtime: config['runtime'] || 'claude' }
+            : null;
+        const policyModel = resolveModelPolicy(mergedPolicy, profileTier);
+        if (policyModel) {
+            // Map the policy-resolved id back to a tier alias with the same
+            // own-property-guarded lookups used above. If it maps, that alias IS
+            // the tier that actually runs — report it (the fix). If it does not
+            // map — including every non-Claude runtime, where resolveModelInternal
+            // returns the policy model verbatim with no tier meaning — the model
+            // carries no tier we can name; report 'unknown' rather than falling
+            // back to the profile tier, which would silently reintroduce the
+            // under-report this block exists to close.
+            const aliasForId = Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, policyModel)
+                ? CLAUDE_POLICY_ID_TO_ALIAS[policyModel]
+                : undefined;
+            if (typeof aliasForId === 'string' && aliasForId)
+                return aliasForId;
+            if (model_catalog_cjs_1.CLAUDE_AGENT_ALIASES.has(policyModel))
+                return policyModel;
+            return 'unknown';
+        }
+    }
+    return profileTier || 'unknown';
+}
+function resolveTierInternal(cwd, agentType) {
+    return resolveTierFromConfig(loadConfig(cwd), agentType);
+}
 function resolveModelInternal(cwd, agentType) {
     const config = loadConfig(cwd);
     // 1. Per-agent override (#2041: map Claude full IDs → Agent-tool aliases on
     // the claude runtime, mirroring the model_policy path #1144; non-Claude
     // runtimes and non-Claude values pass through verbatim).
     const modelOverrides = config['model_overrides'];
-    const override = modelOverrides?.[agentType];
+    // Own-property guard (see resolveTierFromConfig above): without it, an
+    // agentType of "toString" against `model_overrides: {}` returned the
+    // inherited Function.prototype.toString as the resolved "model" — verified
+    // reachable purely via the CLI, no override value needed.
+    const override = (modelOverrides && Object.hasOwn(modelOverrides, agentType))
+        ? modelOverrides[agentType]
+        : undefined;
     if (override) {
         const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
         if (mapped !== null)
             return mapped;
         // Unmappable Claude ID — fall through to tier resolution (matches model_policy).
     }
-    // 2. Compute the tier
+    // 2. Compute the tier (#2229: shared with resolveTierFromConfig so the tier a
+    // workflow reads and the tier a model is resolved from can never diverge).
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     const profile = String(config['model_profile'] || 'balanced').toLowerCase();
-    const agentModels = MODEL_PROFILES[agentType];
-    const phaseType = (AGENT_TO_PHASE_TYPE)[agentType];
-    const configModels = config['models'];
-    const phaseTypeTier = (phaseType && configModels && typeof configModels === 'object')
-        ? configModels[phaseType]
-        : undefined;
-    const tier = (phaseTypeTier && model_catalog_cjs_1.VALID_TIERS.has(phaseTypeTier))
-        ? phaseTypeTier
-        : (profile === 'inherit'
-            ? 'inherit'
-            : (agentModels ? (agentModels[profile] || agentModels['balanced']) : null));
+    // Own-property guard (see computeProfileTier above): without it, agentType
+    // "toString" returned Function.prototype.toString as `agentModels`
+    // (truthy), which skipped the "unknown agent" fallback below and made
+    // resolveModelInternal return undefined instead of a tier-derived string.
+    const modelProfilesMapForModel = MODEL_PROFILES;
+    const agentModels = Object.hasOwn(modelProfilesMapForModel, agentType) ? modelProfilesMapForModel[agentType] : undefined;
+    const tier = computeProfileTier(config, agentType);
     // 2.5. model_policy preset (#49, #1133)
     const configRuntime = config['runtime'];
     if (tier && tier !== 'inherit') {
@@ -320,11 +451,13 @@ function resolveModelInternal(cwd, agentType) {
                 return policyModel;
             // Claude Code's Agent tool takes tier aliases (opus/sonnet/haiku/fable),
             // not full model IDs — map the policy-resolved ID back to an alias (#1133).
-            const aliasForId = CLAUDE_POLICY_ID_TO_ALIAS[policyModel];
-            if (aliasForId)
+            const aliasForId = Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, policyModel)
+                ? CLAUDE_POLICY_ID_TO_ALIAS[policyModel]
+                : undefined;
+            if (typeof aliasForId === 'string' && aliasForId)
                 return aliasForId;
             // The policy value may already be a bare Claude agent alias (e.g. "fable").
-            if (CLAUDE_AGENT_ALIASES.has(policyModel))
+            if (model_catalog_cjs_1.CLAUDE_AGENT_ALIASES.has(policyModel))
                 return policyModel;
             // No Claude alias for this ID (e.g. a pinned minor version like
             // claude-opus-4-5). Warn once and fall through to the tier alias rather
@@ -415,7 +548,13 @@ function resolveModelForTier(cwd, agentType, attempt) {
     const config = loadConfig(cwd);
     const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
     const modelOverrides = config['model_overrides'];
-    const override = modelOverrides?.[agentType];
+    // Own-property guard (see resolveTierFromConfig above): without it, an
+    // agentType of "toString" against `model_overrides: {}` returned the
+    // inherited Function.prototype.toString as the resolved "model" — verified
+    // reachable purely via the CLI, no override value needed.
+    const override = (modelOverrides && Object.hasOwn(modelOverrides, agentType))
+        ? modelOverrides[agentType]
+        : undefined;
     if (override) {
         const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
         if (mapped !== null)
@@ -533,7 +672,12 @@ function resolveProviderEscalation(cwd, agentType, attempt, applicable) {
 }
 // ─── #443 — Unified effort + fast_mode resolvers ─────────────────────────────
 const VALID_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
-const EFFORT_SET = new Set(VALID_EFFORTS);
+// #3533 (10d): the VOCABULARY carries one more member than the LADDER —
+// 'inherit' is a declarable effort choice ("follow the session", expressed by
+// OMITTING the effort key at the writer) but not a level nextEffort may step
+// into. Keeping it out of VALID_EFFORTS means escalation (resolveEffortForTier)
+// never walks past an explicit inherit: nextEffort('inherit') is null.
+const EFFORT_SET = new Set([...VALID_EFFORTS, 'inherit']);
 /**
  * Walk one step up the effort ladder from `e`.
  */
@@ -576,26 +720,23 @@ function resolveEffortInternal(cwd, agentType, opts) {
         }
     }
     // Step 3: routing_tier_defaults by agent's default tier.
+    // #3531 (10c): the config block merges OVER the manifest tier defaults
+    // rather than replacing them — an effort block without
+    // routing_tier_defaults (or missing this agent's tier) falls back to the
+    // manifest built-in for that tier instead of skipping to effort.default.
+    // Invalid config values are dropped by the merge, so the manifest value for
+    // the tier surfaces (the same "invalid falls through" rule every layer has).
     const agentTier = (AGENT_DEFAULT_TIERS)[agentType];
     if (agentTier) {
-        if (effortCfg && effortCfg['routing_tier_defaults'] &&
-            typeof effortCfg['routing_tier_defaults'] === 'object' &&
-            !Array.isArray(effortCfg['routing_tier_defaults'])) {
-            const v = effortCfg['routing_tier_defaults'][agentTier];
-            if (typeof v === 'string' && EFFORT_SET.has(v))
-                return v;
-        }
-        else if (!effortCfg) {
-            const canonicalEffort = (configuration_cjs_1.CONFIG_DEFAULTS)['effort'];
-            const manifestDefaults = canonicalEffort && typeof canonicalEffort === 'object'
-                ? canonicalEffort['routing_tier_defaults']
-                : undefined;
-            if (manifestDefaults && typeof manifestDefaults === 'object') {
-                const v = manifestDefaults[agentTier];
-                if (typeof v === 'string' && EFFORT_SET.has(v))
-                    return v;
-            }
-        }
+        const canonicalEffort = (configuration_cjs_1.CONFIG_DEFAULTS)['effort'];
+        const manifestDefaults = canonicalEffort && typeof canonicalEffort === 'object'
+            ? canonicalEffort['routing_tier_defaults']
+            : undefined;
+        const isValidEffort = (v) => typeof v === 'string' && EFFORT_SET.has(v);
+        const merged = (0, model_catalog_cjs_1.mergeEffortTierDefaults)(manifestDefaults, effortCfg ? effortCfg['routing_tier_defaults'] : undefined, isValidEffort);
+        const v = merged[agentTier];
+        if (isValidEffort(v))
+            return v;
     }
     // Step 4: effort.default
     if (effortCfg) {
@@ -693,9 +834,11 @@ function resolveEffortForTier(cwd, agentType, attempt) {
 }
 module.exports = {
     resolveTierEntry,
-    CLAUDE_AGENT_ALIASES,
+    CLAUDE_AGENT_ALIASES: model_catalog_cjs_1.CLAUDE_AGENT_ALIASES,
     resolveModelPolicy,
     resolveModelInternal,
+    resolveTierInternal,
+    resolveTierFromConfig,
     _resetModelPolicyWarningCacheForTests,
     _resetModelOverrideWarningCacheForTests,
     _setInstallRuntimeMarkerForTests,

package/gsd-core/bin/lib/normalize-test-command.cjs

@@ -23,7 +23,7 @@
  * hang or take super-linear time on an adversarial `workflow.test_command`.
  *
  * Single source of truth: all four test-command gates (regression, post-merge,
- * audit-fix, verify-phase) route their resolved command through this helper so
+ * audit-fix) route their resolved command through this helper so
  * the paths cannot drift.
  *
  * Leaf module — depends only on node:fs / node:path.

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

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * pattern.cts — the pattern-construction seam (ADR-3212 §1, epic #3212 Phase 1,
+ * #3412).
+ *
+ * Source in src/pattern.cts, compiled to gsd-core/bin/lib/pattern.cjs
+ * (gitignored), per the repo's ADR-457 build-at-publish convention.
+ *
+ * Sole owner of building a `RegExp` from a runtime value. `escapeRegex`
+ * delegates to the built-in `RegExp.escape` (ES2026 / Node 24+) when present,
+ * falling back to an in-file metacharacter escape below Node 24 (#3498) —
+ * still the one owner: no module outside this seam escapes a value for regex
+ * use (ADR §1).
+ *
+ * Counts, corrected during implementation (design doc "Ground truth" #1;
+ * .gsd/phase/chore-3412-pattern-seam/40-design.md): the ADR's census counted
+ * ~12 *named* helper functions. The shape-based lint guard
+ * (eslint-rules/no-adhoc-regex-escape.cjs), which matches the escape-class
+ * SHAPE wherever it appears rather than named-function bodies, found 27
+ * additional inline copies that census-by-name could not see — **~39 escape
+ * sites total**. Call sites follow the same pattern: 17 were surveyed
+ * directly, but `src/phase-id.cts`'s `escapeRegex` turned out to have 8
+ * external production importers the pre-implementation survey missed, plus
+ * the 27 guard-found inline sites also call into the seam — **~44 call
+ * sites total**. The lesson worth keeping: a named-function census
+ * structurally cannot see an inline `.replace(...)` copy or an
+ * externally-imported symbol; only a shape-based guard (or a direct
+ * importer graph query) does.
+ *
+ * `escapeRegex` is the PRIMARY export: the large majority of call sites
+ * build a *source string* (alternation via `.map(escapeRegex).join('|')`, or
+ * template/concat interpolation into a larger pattern) rather than a
+ * standalone literal match. `literalPattern` is the minority convenience
+ * wrapper for the remaining "match this value literally" shape — not the
+ * dominant one (design doc "Ground truth" #2).
+ *
+ * Behavior-preserving for MATCH RESULTS, not for pattern TEXT: `RegExp.escape`
+ * hex-escapes the leading character of nearly every non-empty input (and `-`,
+ * space, and control characters throughout), so the escaped source string
+ * differs from the twelve deleted copies' output for almost every value.
+ * Match behavior against that source is unaffected — verified by the
+ * migration-equivalence property sweep in tests/pattern.test.cjs (rows 15-17).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_USER_PATTERN_LEN = void 0;
+exports.escapeRegex = escapeRegex;
+exports.literalPattern = literalPattern;
+exports.compileUserPattern = compileUserPattern;
+// re2js is vendored, not an npm dependency at runtime: gsd-core/bin/** is
+// copied into installed trees that have no node_modules, so this module must
+// carry zero external requires (eslint-rules/no-external-require-in-bin.cjs
+// enforces it). See gsd-core/bin/lib/vendor/README.md.
+const re2js_cjs_1 = require("./vendor/re2js.cjs");
+// #3498: RegExp.escape is ES2026 (first shipped in Node 24). The gsd-test
+// matrix still runs a linux-node22 lane, and the build itself consumes this
+// module (scripts/gen-loop-host-contract.cjs), so a hard dependency breaks
+// `npm run build` on Node 22. Prefer the built-in when present; otherwise use
+// the local metachar escape — still inside this file, so the #3212 sole-owner
+// invariant (and lint-no-adhoc-regex-escape's scope) is preserved. Captured at
+// module load so a runtime mutation of RegExp.escape cannot flip the path
+// mid-process.
+const escapeBuiltin = typeof RegExp.escape === 'function'
+    ? RegExp.escape.bind(RegExp)
+    : undefined;
+const escapeMetachars = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function escapeRegex(value) {
+    return (escapeBuiltin ?? escapeMetachars)(value);
+}
+function literalPattern(value, flags) {
+    return new RegExp(escapeRegex(value), flags);
+}
+/** Max length for a user-supplied regex pattern before it is refused (ReDoS/compile-cost mitigation). */
+exports.MAX_USER_PATTERN_LEN = 512;
+/** Always-false matcher shared by every neutralization path — a refused pattern must never be able to report a match. */
+const NEVER_MATCH = () => false;
+/**
+ * Compile an UNTRUSTED, user-supplied pattern (e.g. plan frontmatter) via RE2
+ * (re2js), whose matching is linear-time in input length by construction —
+ * there is no backtracking engine here to exploit, so the vulnerability class
+ * (catastrophic/exponential backtracking) is closed by the engine rather than
+ * detected by a heuristic scan of the pattern text.
+ *
+ * Never throws. A pattern that is empty, too long, or not valid RE2 syntax
+ * (backreferences and look-around are unsupported by RE2 — those are exactly
+ * the constructs that require backtracking) is REFUSED: `test()` always
+ * returns `false`, and `neutralized` reports why so callers can surface the
+ * refusal (#3477 follow-up: a neutralized pattern must not look like a plain
+ * "not found"). Restores the guards lost with
+ * `sdk/src/query/validate.ts:regexForKeyLinkPattern` (#3477); this revision
+ * (post-#3477-follow-up) replaces the hand-rolled backtracking-shape scanner
+ * with RE2's linear-time guarantee — a refused pattern is never re-attempted
+ * as a literal-escaped match, since guessing at a pattern we could not
+ * compile is what produced the prior false-pass regression.
+ *
+ * `pattern` is `unknown`, not `string`, because callers pull this straight off
+ * parsed plan frontmatter (untrusted YAML) — a non-string value must reach the
+ * `'empty'`/never-match branch rather than being force-cast by the caller.
+ */
+function compileUserPattern(pattern) {
+    if (typeof pattern !== 'string' || pattern.length === 0) {
+        return { test: NEVER_MATCH, neutralized: 'empty' };
+    }
+    if (pattern.length > exports.MAX_USER_PATTERN_LEN) {
+        // The cap now bounds compile cost/memory, not backtracking (RE2 has none) —
+        // an over-long pattern is refused outright rather than truncated-and-compiled.
+        return { test: NEVER_MATCH, neutralized: 'too-long' };
+    }
+    try {
+        // translateRegExp accepts JS-flavored syntax (named groups, `/`-escaping,
+        // etc.) that RE2's own grammar doesn't, reducing spurious refusals of
+        // otherwise-safe, JS-authored patterns before compiling under RE2's
+        // linear-time engine.
+        const compiled = re2js_cjs_1.RE2JS.compile(re2js_cjs_1.RE2JS.translateRegExp(pattern));
+        return { test: (input) => compiled.test(input), neutralized: null };
+    }
+    catch {
+        // Backreferences, look-around, or any other RE2-unsupported/malformed
+        // syntax. No literal-escape fallback: a pattern we could not compile is
+        // never guessed at — guessing produced the #3477 false-pass regression.
+        return { test: NEVER_MATCH, neutralized: 'unsupported' };
+    }
+}

package/gsd-core/bin/lib/phase-estimation.cjs

@@ -231,7 +231,7 @@ function extractFrontmatterBlock(text, key) {
     if (typeof text !== 'string')
         return null;
     // Anchor at byte 0 — CRLF-tolerant.
-    const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?(?:\n|$)/.exec(text);
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|\r?$)/.exec(text);
     if (fm === null)
         return null;
     const lines = fm[1].split(/\r?\n/);