@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/bin/lib/install-engine.cjs

@@ -23,6 +23,7 @@ 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 runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
+const security_cjs_1 = require("./security.cjs");
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
@@ -111,7 +112,7 @@ function previousOwnedCorpusFiles(configDir, prefix) {
 }
 function pruneEmptyCorpusParents(start, stop) {
     let current = node_path_1.default.dirname(start);
-    while (current !== stop && current.startsWith(stop + node_path_1.default.sep)) {
+    while (current !== stop && current.startsWith(stop + node_path_1.default.sep)) { // allow-handrolled-containment: ancestor-walk loop condition, not a containment gate
         if (installFs().readdirSync(current).length > 0)
             return;
         installFs().rmdirSync(current);
@@ -347,8 +348,11 @@ function hasExistingSymlinkBetween(root, fullPath, options = {}) {
     const resolvedFullPath = node_path_1.default.resolve(fullPath);
     // (a) Path-traversal refusal — ALWAYS enforced, even with opt-in. An untrusted
     // destSubpath string that escapes the install root via '..' is rejected
-    // regardless of user opt-in state (ADR-1239 Phase B threat (a)).
-    if (resolvedFullPath !== resolvedRoot && !resolvedFullPath.startsWith(resolvedRoot + node_path_1.default.sep)) {
+    // regardless of user opt-in state (ADR-1239 Phase B threat (a)). Lexical
+    // (ADR-4650 decision 6): this function's whole purpose is to DETECT
+    // symlinks between root and target, so resolving them here would erase what
+    // it measures.
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedFullPath, resolvedRoot) === null) {
         return true;
     }
     // #2393 (security-review finding): realpathSync fully resolves all symlink
@@ -1492,6 +1496,15 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
             content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
             content = processAttribution(content, resolveAttribution(runtime));
             const skillDir = node_path_1.default.join(dest, skillName);
+            // isPathConfined is lexical and cannot see a symlink. mkdirSync({recursive:true})
+            // does NOT throw when skillDir already exists as a symlink to a directory, so a
+            // pre-planted link would redirect the SKILL.md write outside `dest`. Refuse to
+            // write through a link (epic #4636; mirrors retired-artifact-cleanup.cts:77).
+            try {
+                if (installFs().lstatSync(skillDir).isSymbolicLink())
+                    continue;
+            }
+            catch { /* ENOENT: not created yet — the normal case */ }
             installFs().mkdirSync(skillDir, { recursive: true });
             installFs().writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
             // #2322 HIGH-3 parity: persist the capability-owned marker so a later

package/gsd-core/bin/lib/install-profiles.cjs

@@ -740,6 +740,11 @@ function readInstalledCapabilitySkill(stem, registry) {
         return null;
     const skillPath = node_path_1.default.join(capDir, relSkillPath);
     try {
+        // statSync follows symlinks; isPathConfined is lexical and cannot see one.
+        // Refuse to read through a link so an outside file's content cannot be
+        // installed as a capability skill (epic #4636).
+        if (node_fs_1.default.lstatSync(skillPath).isSymbolicLink())
+            return null;
         if (!node_fs_1.default.statSync(skillPath).isFile())
             return null;
         return { capId, content: node_fs_1.default.readFileSync(skillPath, 'utf8') };
@@ -858,6 +863,15 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
                 if (!(0, external_descriptor_trust_cjs_1.isPathConfined)(skillName, stageDir))
                     continue; // defense-in-depth
                 const destDir = node_path_1.default.join(stageDir, skillName);
+                // isPathConfined is lexical and cannot see a symlink. mkdirSync({recursive:true})
+                // does NOT throw when destDir already exists as a symlink to a directory, so a
+                // pre-planted link would redirect the SKILL.md write outside `stageDir`. Refuse
+                // to write through a link (epic #4636; mirrors retired-artifact-cleanup.cts:77).
+                try {
+                    if (installFs().lstatSync(destDir).isSymbolicLink())
+                        continue;
+                }
+                catch { /* ENOENT: not created yet — the normal case */ }
                 installFs().mkdirSync(destDir, { recursive: true });
                 installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), found.content);
                 // #2322 HIGH-3: persist the capability-owned marker so a later prune

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -17,6 +17,7 @@ const installer_migration_authoring_cjs_1 = require("./installer-migration-autho
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 const install_scope_cjs_1 = require("./install-scope.cjs");
+const security_cjs_1 = require("./security.cjs");
 // #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
 // plan/apply/rollback/lock/journal engine — almost none of it is on the
 // installRuntimeArtifacts call tree. Only `readInstallManifest` and
@@ -122,8 +123,17 @@ function evaluateRemoveEmptyDir(configDir, fullPath) {
     catch {
         return 'left-in-place';
     }
-    if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(resolvedRoot + node_path_1.default.sep)) {
-        // Refuses both "target IS configDir" and "target escaped configDir".
+    // `resolvedTarget === resolvedRoot` is a DELIBERATE ADDITIONAL rejection,
+    // separate from the containment decision: `tryWithinRootLexical` treats
+    // target === root as CONTAINED, but removing the config root itself is
+    // never in scope for this action (see the doc comment above) — this arm
+    // prevents `rmdirSync` from ever being asked to remove `configDir` itself.
+    // Kept as its own check per ADR-4650 decision 6 (a wrapper may add its own
+    // conditions on top of the canonical predicate, never invert it).
+    if (resolvedTarget === resolvedRoot)
+        return 'left-in-place';
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedTarget, resolvedRoot) === null) {
+        // Refuses "target escaped configDir".
         return 'left-in-place';
     }
     let entries;
@@ -598,11 +608,30 @@ function acquireInstallMigrationLock(configDir, { timeoutMs = DEFAULT_LOCK_TIMEO
         }
     }
 }
+// DELIBERATELY LEXICAL — the RESOLUTION policy stays lexical, never realpath
+// (`assertWithinRoot` / `tryWithinRoot`, src/security.cts).
+//
+// Reviewed under epic #4636 Phase 3 and reverted after the remote matrix proved
+// the realpath collapse wrong. This module's contract is that a symlinked
+// managed path is treated AS A LINK and never dereferenced — it is snapshotted
+// as a link, restored as a link, and backed up as a link. The realpath-based
+// predicate dereferences exactly the symlinks this module exists to preserve
+// and then rejects them for escaping configDir
+// ("migration path escapes configDir: extensions/gsd.cjs"). Four tests in
+// tests/installer-migrations.test.cjs pin that behavior.
+//
+// The containment DECISION now routes through the canonical LEXICAL predicate
+// (`tryWithinRootLexical`, ADR-4650 decision 6) — only the comparison moved;
+// the lexical policy itself remains this module's own required choice, and
+// the thrown message / returned `fullPath` are unchanged.
+//
+// `normalizeRelPath` is the pre-gate: it throws on absolute paths and on any
+// '..' segment BEFORE this runs, so the check below is defense-in-depth over
+// already-traversal-free input rather than the primary boundary.
 function ensureInsideConfig(configDir, relPath) {
     const normalized = normalizeRelPath(relPath);
     const fullPath = node_path_1.default.resolve(configDir, normalized);
-    const root = node_path_1.default.resolve(configDir);
-    if (fullPath !== root && !fullPath.startsWith(root + node_path_1.default.sep)) {
+    if ((0, security_cjs_1.tryWithinRootLexical)(fullPath, configDir) === null) {
         throw new Error(`migration path escapes configDir: ${relPath}`);
     }
     return { normalized, fullPath };

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

@@ -224,6 +224,9 @@ function resolveLoopHooks(input) {
             active.consumes = consumes;
         if (onError !== undefined)
             active.onError = onError;
+        // #4209 DISP-02: only a literal `true` projects; absent/false stay inert.
+        if (hook['supportsReviewerLanes'] === true)
+            active.supportsReviewerLanes = true;
         activeHooks.push(active);
     }
     // Process contributions
@@ -422,17 +425,20 @@ function sanitizeLoadFailReason(reason) {
         .slice(0, 300);
     return cleaned || '(no reason given)';
 }
-function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
-    if (!point) {
-        coreError('loop render-hooks requires a <point> argument. Valid points: ' + CANONICAL_POINTS.join(', '));
-        return;
-    }
-    // --active-cap <capId> mode: emit 'true' or 'false' only (scanner-safe, no JSON envelope)
-    const activeCapId = typeof options['activeCap'] === 'string' ? options['activeCap'] : undefined;
-    if (activeCapId !== undefined && activeCapId === '') {
-        coreError('--active-cap requires a <capId> value (e.g. --active-cap tdd)');
-        return;
-    }
+/**
+ * The full config/registry/capability-state resolution `cmdLoopRenderHooks` performs, minus its
+ * CLI-only output formatting — extracted so an in-process caller (e.g. `review-lane dispatch-step`
+ * self-verifying a `supportsReviewerLanes` trait) can reach the SAME resolution `gsd_run loop
+ * render-hooks <point> --raw` would give it, without spawning a subprocess and re-parsing its
+ * stdout (which was subject to `io.cjs`'s `@file:` overflow protocol on the rendered-string
+ * envelope — a bug class this in-process call cannot hit, since it never touches that envelope
+ * or its rendering at all).
+ *
+ * Throws on an invalid `point` (mirrors `resolveLoopHooks`); callers convert to their own error
+ * channel. Emits the same loud stderr load-failure warnings `cmdLoopRenderHooks` always has,
+ * regardless of caller — a skipped gate must never be silently invisible.
+ */
+function resolveActiveHooksForPoint(cwd, point, options = {}) {
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;
@@ -468,15 +474,7 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     for (const cap of state.capabilities || []) {
         capabilityStatesById.set(cap.id, cap);
     }
-    let resolved;
-    try {
-        resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
-    }
-    catch (err) {
-        const msg = (err instanceof Error) ? err.message : String(err);
-        coreError(msg);
-        return;
-    }
+    const resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
     // ── ADR-1244 D2: load-failed capability gates FAIL OPEN with a loud warning ────
     // Decision (#2009): a capability that failed to LOAD must not block the loop.
     // The prior behavior injected a BLOCKING synthetic gate (blocking:true,
@@ -525,24 +523,44 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     for (const w of loadFailWarnings) {
         process.stderr.write(`gsd: warning — ${w}\n`);
     }
-    // --active-cap mode: print exactly 'true' or 'false' with no envelope
+    // Surface capability-state warnings and the #2009 load-failure fail-open warnings together
+    // (in addition to the stderr emission above, which is the channel host workflows actually see).
+    const combinedWarnings = [...(state.warnings || []), ...loadFailWarnings];
+    return { point: resolved.point, activeHooks: resolved.activeHooks, warnings: combinedWarnings };
+}
+function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
+    if (!point) {
+        coreError('loop render-hooks requires a <point> argument. Valid points: ' + CANONICAL_POINTS.join(', '));
+        return;
+    }
+    // --active-cap <capId> mode: emit 'true' or 'false' only (scanner-safe, no JSON envelope)
+    const activeCapId = typeof options['activeCap'] === 'string' ? options['activeCap'] : undefined;
+    if (activeCapId !== undefined && activeCapId === '') {
+        coreError('--active-cap requires a <capId> value (e.g. --active-cap tdd)');
+        return;
+    }
+    let result;
+    try {
+        result = resolveActiveHooksForPoint(cwd, point, options);
+    }
+    catch (err) {
+        const msg = (err instanceof Error) ? err.message : String(err);
+        coreError(msg);
+        return;
+    }
     if (activeCapId !== undefined) {
-        const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
+        const isActive = result.activeHooks.some((h) => h.capId === activeCapId);
         process.stdout.write(isActive ? 'true\n' : 'false\n');
         return;
     }
-    const rendered = renderLoopHooks(resolved);
+    const rendered = renderLoopHooks({ point: result.point, activeHooks: result.activeHooks });
     const envelope = {
-        point: resolved.point,
-        activeHooks: resolved.activeHooks,
+        point: result.point,
+        activeHooks: result.activeHooks,
         rendered,
     };
-    // Surface capability-state warnings and the #2009 load-failure fail-open
-    // warnings together in the structured `warnings` channel (in addition to the
-    // stderr emission above, which is the channel host workflows actually see).
-    const combinedWarnings = [...(state.warnings || []), ...loadFailWarnings];
-    if (combinedWarnings.length > 0) {
-        envelope.warnings = combinedWarnings;
+    if (result.warnings.length > 0) {
+        envelope.warnings = result.warnings;
     }
     coreOutput(envelope, raw);
 }
@@ -550,6 +568,7 @@ module.exports = {
     resolveLoopHooks,
     renderLoopHooks,
     cmdLoopRenderHooks,
+    resolveActiveHooksForPoint,
     // Exported for tests
     _getNestedConfigValue,
     _resolveActivationValue,

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

@@ -402,8 +402,8 @@ function classifyUnindexedUri(uri) {
 }
 /** Second, independent gate (design "Hostile inputs" gate 2): re-validate an INDEXED entry's relPath against the catalog root, catching a symlink planted after the index was built. */
 function readIndexedResource(catalog, entry) {
-    const check = (0, security_cjs_1.validatePath)(entry.relPath, catalog.root);
-    if (!check.safe) {
+    const contained = (0, security_cjs_1.tryWithinRoot)(entry.relPath, catalog.root);
+    if (contained === null) {
         fail(exports.REASON.TRAVERSAL_REFUSED, `indexed resource escapes catalog root: ${entry.relPath}`);
     }
     let raw;

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

@@ -826,7 +826,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         // never disagree with what a real run actually archives. Absent
         // --archive-quick this stays `[]` and nothing on disk is touched either
         // way (dry-run always returns before any mutation below).
-        const quickDirsToArchive = options.archiveQuick ? listQuickTaskDirsForArchive(cwd) : [];
+        const quickDirsToArchive = options.archiveQuick ? listQuickTaskDirsForArchive(cwd).map((d) => d.name) : [];
         const dryRunResult = {
             dry_run: true,
             version,
@@ -1482,6 +1482,16 @@ function writeQuickArchiveReadme(archiveQuickDir) {
  * written three times, and only the real-run copy applied `requireSafePath`,
  * so a dry-run preview could list a directory the real run would silently
  * skip).
+ *
+ * Returns the proven `ContainedPath` alongside each entry's bare `name`
+ * (`no-unconfined-path-join`'s `discardedContainmentResult` arm — a bare
+ * statement call to `requireSafePath` throws away the exact answer it just
+ * computed). The two dry-run previews only need `name` for display;
+ * `archiveQuickTaskDirectories` deliberately does NOT reuse `abs` for its
+ * rename — it re-derives and re-validates independently as TOCTOU
+ * defense-in-depth (see its own comment), so `abs` exists here only to make
+ * this function's own discard explicit, not to be trusted downstream as a
+ * stale-safe proof.
  */
 function listQuickTaskDirsForArchive(cwd) {
     const planningBase = planningPaths(cwd).planning;
@@ -1494,19 +1504,20 @@ function listQuickTaskDirsForArchive(cwd) {
         // .planning/quick absent or unreadable — nothing to select.
         return [];
     }
-    const names = [];
+    const results = [];
     for (const entry of sourceEntries) {
         if (!entry.isDirectory())
             continue; // excludes symlinks too — see MAJOR 3 note above
+        let abs;
         try {
-            (0, security_cjs_1.requireSafePath)(node_path_1.default.join(quickDir, entry.name), planningBase, 'quick task dir', { allowAbsolute: true });
+            abs = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(quickDir, entry.name), planningBase, 'quick task dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue; // symlink/escape attempt — never a candidate, in preview OR real run
         }
-        names.push(entry.name);
+        results.push({ name: entry.name, abs });
     }
-    return names.sort();
+    return results.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 /**
  * #2142: move each DIRECTORY entry under `.planning/quick/` into
@@ -1555,7 +1566,7 @@ function archiveQuickTaskDirectories(cwd, version) {
     // #2142 MAJOR 5 (review): dirNames is the SAME selection
     // `listQuickTaskDirsForArchive` hands to both dry-run previews — this is
     // the real run, so it cannot disagree with what a preview reported.
-    const dirNames = listQuickTaskDirsForArchive(cwd);
+    const dirNames = listQuickTaskDirsForArchive(cwd).map((d) => d.name);
     if (dirNames.length === 0) {
         // Boundary 0 (#2142): zero (safe) directory entries (empty dir, only
         // stray files, or every entry excluded by the selection rule) must not
@@ -1576,7 +1587,7 @@ function archiveQuickTaskDirectories(cwd, version) {
                 // rename are two separate filesystem observations, and an entry
                 // that was a safe real directory at selection time could in theory
                 // be swapped for a symlink before this loop reaches it.
-                safeSrc = (0, security_cjs_1.requireSafePath)(src, planningBase, 'quick task dir', { allowAbsolute: true });
+                safeSrc = (0, security_cjs_1.requireSafePath)(src, planningBase, 'quick task dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue; // symlink/escape attempt — skip, not archived
@@ -1669,7 +1680,7 @@ function cmdQuickArchive(cwd, version, options, raw) {
     // `cmdMilestoneComplete`'s own dry-run preview and the real
     // `archiveQuickTaskDirectories` both use, so all three can never disagree.
     if (options.dryRun) {
-        const quickDirsToArchive = listQuickTaskDirsForArchive(cwd);
+        const quickDirsToArchive = listQuickTaskDirsForArchive(cwd).map((d) => d.name);
         output({
             dry_run: true,
             version,

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

@@ -128,6 +128,67 @@ function _resolveRuntimeTier(config, tier) {
         overrides: config['model_profile_overrides'],
     });
 }
+/**
+ * #4192 — Resolve the claude-runtime TIER OVERRIDE model for (config, tier).
+ *
+ * Step 3's runtime-aware resolution deliberately skips the claude runtime to
+ * preserve the alias-native posture (#1156/#2297): with no user override, the
+ * resolver must keep returning bare tier aliases, and the builtin claude tier
+ * map (`opus → claude-opus-4-8`, …) must never force full-ID emission on every
+ * default install. But `model_profile_overrides.<runtime>.<tier>` is a
+ * documented override point (docs/CONFIGURATION.md § Runtime-Aware Profiles)
+ * that `workflows/settings-advanced.md` actively writes for claude-runtime
+ * users — and #4192 Finding 1 measured the key inert on this runtime.
+ *
+ * This helper reads ONLY the user's override entry for the effective claude
+ * runtime and tier — never the builtin claude tier map — so an install with no
+ * override is byte-identical to before the fix. The runtime is resolved the
+ * same way steps 1-3 resolve it (config['runtime'], defaulting to 'claude'),
+ * NOT via resolveActiveRuntime (GSD_RUNTIME/marker): the value policy must
+ * key off the config the operator wrote, matching mapClaudeOverrideForRuntime.
+ *
+ * Value policy mirrors the model_overrides path (#2041/#4192): an override
+ * value that maps to a current tier alias collapses to that alias
+ * (byte-equivalent resolution, alias-form emission); anything else — a pinned
+ * older generation (`claude-opus-4-7`), a bare alias/tier repoint (`sonnet`),
+ * or a non-Claude vendor id (`openai/o3`) — is emitted verbatim as pinned.
+ * Malformed entries (no usable `model` string) return null so the caller falls
+ * through to normal alias resolution (ADR-443 D1: invalid values fall through).
+ */
+function resolveClaudeTierOverrideModel(configRuntime, tier, overrides) {
+    if (!tier || tier === 'inherit')
+        return null;
+    const effectiveRuntime = configRuntime || 'claude';
+    if (effectiveRuntime !== 'claude')
+        return null; // non-claude runtimes resolve at step 3
+    const overridesMap = overrides;
+    if (!overridesMap || typeof overridesMap !== 'object')
+        return null;
+    // Own-property guards throughout: both levels are config-supplied plain
+    // objects, so a prototype-chain key ("constructor", "toString") must not
+    // resolve an inherited member instead of falling through (same hardening as
+    // every other config-keyed lookup in this module).
+    const runtimeEntry = Object.hasOwn(overridesMap, effectiveRuntime)
+        ? overridesMap[effectiveRuntime]
+        : undefined;
+    if (!runtimeEntry || typeof runtimeEntry !== 'object')
+        return null;
+    const userRaw = Object.hasOwn(runtimeEntry, tier) ? runtimeEntry[tier] : undefined;
+    if (userRaw === undefined || userRaw === null)
+        return null;
+    const entry = typeof userRaw === 'string'
+        ? { model: userRaw }
+        : userRaw;
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const model = entry['model'];
+    if (typeof model !== 'string' || model.length === 0)
+        return null;
+    if (Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, model)) {
+        return CLAUDE_POLICY_ID_TO_ALIAS[model];
+    }
+    return model;
+}
 // Reverse of the Claude tier-default IDs, plus the Fable alias which Claude
 // Code's Agent tool accepts but which is not a GSD model-profile tier (#1133).
 const CLAUDE_POLICY_ID_TO_ALIAS = {
@@ -154,7 +215,10 @@ function warnModelPolicyUnmappable(agentType, policyModel, tier) {
 function _resetModelPolicyWarningCacheForTests() {
     _modelPolicyUnmappableWarned.clear();
 }
-// Dedupe stderr warnings for unmappable model_overrides Claude IDs (#2041).
+// Dedupe stderr warnings for unmappable model_overrides Claude IDs (#2041 /
+// #4192). #2041 originally warned that such a value was being DROPPED to tier
+// resolution; #4192 keeps the warn-once breadcrumb but changes the behavior to
+// a verbatim pass-through, so the text now describes the pass-through.
 const _modelOverrideUnmappableWarned = new Set();
 function warnModelOverrideUnmappable(agentType, overrideValue) {
     const key = `${agentType}::${overrideValue}`;
@@ -165,8 +229,9 @@ function warnModelOverrideUnmappable(agentType, overrideValue) {
     // full to stderr/logs (#2041 security review). MUST go to stderr — resolve-
     // model's JSON result is parsed from stdout.
     const safe = overrideValue.length > 64 ? overrideValue.slice(0, 64) + '…' : overrideValue;
-    process.stderr.write(`gsd: warning — model_overrides value "${safe}" for ${agentType} ` +
-        `has no Claude agent alias; falling through to tier resolution.\n`);
+    process.stderr.write(`gsd: warning — model_overrides value "${safe}" for ${agentType} is a fully-qualified ` +
+        `Claude model ID with no tier alias; passing it through verbatim. Claude Code setups ` +
+        `whose Agent tool accepts only tier aliases will not honor it. (#4192)\n`);
 }
 // Test-only: reset the model_overrides warn-dedupe cache between cases (#2041).
 function _resetModelOverrideWarningCacheForTests() {
@@ -175,12 +240,24 @@ function _resetModelOverrideWarningCacheForTests() {
 /**
  * #2041 — Map a `model_overrides` value to its Claude Agent-tool alias on the
  * claude runtime, mirroring the `model_policy` path (#1144). Claude Code's
- * Agent tool `model` parameter documents only tier aliases (opus/sonnet/haiku/
- * fable); a full Claude model ID returned verbatim is silently dropped by the
- * spawner. Returns the value to return verbatim, or null to signal "fall
- * through to normal tier/dynamic-routing resolution" (used when a Claude full
- * ID has no alias — matches model_policy's warn-and-fall-through). Non-Claude
- * runtimes and non-Claude values always pass through verbatim.
+ * Agent tool `model` parameter documents tier aliases (opus/sonnet/haiku/
+ * fable) as the always-accepted form. Returns the value to emit verbatim, or
+ * null to signal "fall through to normal tier/dynamic-routing resolution".
+ * Non-Claude runtimes and non-Claude values always pass through verbatim.
+ *
+ * #4192 — an unmappable `claude-*` value (a pinned generation that is not the
+ * current catalog default, e.g. `claude-opus-4-7`) is now PASSED THROUGH
+ * VERBATIM with a warn-once stderr breadcrumb, instead of being dropped to
+ * tier resolution. #2041's drop was correct when the value was plausibly a
+ * mis-typed current default, but for an explicit pin it silently UNPINNED the
+ * operator's choice — the resolver would report a tier the config never asked
+ * for, the exact "profile can misrepresent what actually runs" defect #4192
+ * files. The documented contract ("any fully-qualified model ID",
+ * docs/CONFIGURATION.md § Per-Agent Overrides,
+ * gsd-core/references/model-profiles.md § Per-Agent Overrides) is restored:
+ * the pin is resolved as configured. Values that DO map to a current tier
+ * alias still collapse to that alias — byte-equivalent resolution, the #2041
+ * protection preserved — and a mappable pin never warns.
  *
  * Hardening (code+security review): a `typeof` guard preserves the pre-fix
  * no-crash behavior if a malformed config surfaces a non-string value, and an
@@ -204,8 +281,9 @@ function mapClaudeOverrideForRuntime(override, configRuntime, agentType) {
     if (model_catalog_cjs_1.CLAUDE_AGENT_ALIASES.has(override))
         return override;
     if (override.startsWith('claude-')) {
+        // #4192: explicit generation pin — resolve as configured (see docblock).
         warnModelOverrideUnmappable(agentType, override);
-        return null;
+        return override;
     }
     return override;
 }
@@ -467,6 +545,19 @@ function resolveModelInternal(cwd, agentType) {
         && (projectExplicitlySetsOmit(cwd) || !RUNTIMES_WITH_NATIVE_ALIASES.has(resolveActiveRuntime(config)))) {
         return '';
     }
+    // 4.5. Claude-runtime tier override (#4192 Finding 1). Sits AFTER the omit
+    // gate so an explicit project `resolve_model_ids:"omit"` still wins (#2297:
+    // explicit project omit is honored regardless of runtime), and BEFORE the
+    // alias return so a pinned generation is not re-collapsed to a tier alias or
+    // re-materialized to the LATEST catalog id by step 5's
+    // `resolve_model_ids:true` path. Fires ONLY when the user wrote a
+    // `model_profile_overrides.claude.<tier>` entry for this tier — see
+    // resolveClaudeTierOverrideModel for why the builtin map stays out.
+    if (tier && tier !== 'inherit') {
+        const claudeOverrideModel = resolveClaudeTierOverrideModel(configRuntime, tier, config['model_profile_overrides']);
+        if (claudeOverrideModel !== null)
+            return claudeOverrideModel;
+    }
     // 5. Profile lookup (Claude-native default).
     if (!agentModels) {
         return profile === 'quality' ? 'opus'

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

@@ -126,7 +126,13 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                 if (args.includes('--dry-run')) {
                     return makeInvalidArgs('--dry-run', 'phase insert does not support --dry-run');
                 }
-                phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
+                // #4569: --sibling opts into joining afterPhase's parent decimal level
+                // instead of nesting one level deeper. Filtered out like other
+                // boolean flags (see `remove`'s --force handling above) so it never
+                // leaks into the free-text description.
+                const sibling = args.includes('--sibling');
+                const insertArgs = args.slice(2).filter(token => token !== '--sibling');
+                phase.cmdPhaseInsert(cwd, insertArgs[0], insertArgs.slice(1).join(' '), raw, sibling ? 'sibling' : 'nested');
                 return { ok: true, data: null };
             },
             remove: (_ctx) => {