@opengsd/gsd-core 1.6.0 → 1.7.0-rc.1

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

@@ -30,13 +30,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROHIBITION_VALIDATORS = exports.VALID_STATUS = void 0;
+exports.INSUFFICIENT_SPEC = exports.PROHIBITION_VALIDATORS = exports.VALID_STATUS = void 0;
 exports.validateRequirement = validateRequirement;
 exports.validateResolution = validateResolution;
 exports.analyzeCoverage = analyzeCoverage;
 exports.validateProhibitionResolution = validateProhibitionResolution;
 exports.projectProhibitions = projectProhibitions;
 exports.dispositionForProhibition = dispositionForProhibition;
+exports.truthStatement = truthStatement;
+exports.truthVerification = truthVerification;
+exports.projectTruths = projectTruths;
+exports.dispositionForUnverifiableTruth = dispositionForUnverifiableTruth;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
@@ -355,6 +359,92 @@ function dispositionForProhibition(prohibition, context = {}) {
         reason: 'judgment-tier prohibition routes to judgment review — never a silent green (ADR-550 D4)',
     };
 }
+/** Extract a truth's statement text from either the string or the object form (the Hyrum normalizer). */
+function truthStatement(truth) {
+    if (typeof truth === 'string')
+        return truth;
+    if (truth != null && typeof truth === 'object') {
+        const s = truth.statement;
+        if (typeof s === 'string')
+            return s;
+    }
+    return '';
+}
+/**
+ * Extract a truth's verification tier, or `null` when it carries none (a plain string, or an object
+ * with no/garbled marker). Failing toward `null` is the Postel-safe direction: an unrecognized marker
+ * grades NORMALLY (never a spurious abstention — the over-abstention guard, AC#3), and the marker is
+ * machine-emitted from validated edge data so garbling is not a live input path.
+ */
+function truthVerification(truth) {
+    if (truth == null || typeof truth !== 'object')
+        return null;
+    const v = truth.verification;
+    return v === 'explicit' || v === 'backstop' ? v : null;
+}
+/**
+ * Conservative serializer (Postel: "send well-formed, minimal data") for projecting truths into a
+ * `must_haves.truths` block — the truth-axis analogue of `projectProhibitions`. A `backstop` truth is
+ * emitted as a flat-scalar object `{ statement, verification: 'backstop' }` (ADR-550 #1278: flat
+ * scalars round-trip the existing `parseMustHavesBlock`; a nested object would mangle it). Every other
+ * truth collapses to a bare statement string — only the non-inferable tier needs a structured marker,
+ * so an `explicit`/inferable truth never carries one (no spurious markers). Empty statements are dropped.
+ */
+function projectTruths(items) {
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const item of items) {
+        const statement = truthStatement(item);
+        if (!statement)
+            continue;
+        if (truthVerification(item) === 'backstop') {
+            out.push({ statement, verification: 'backstop' });
+        }
+        else {
+            out.push(statement);
+        }
+    }
+    return out;
+}
+/** The stable, distinguishable verdict-reason token for an abstained non-inferable truth (review condition 1). */
+exports.INSUFFICIENT_SPEC = 'insufficient_spec';
+/**
+ * Deterministic verify-time disposition for a single truth (ADR-550 D4 truth-axis mirror, #1154).
+ * PURE — no LLM judgment (ADR-550 D5); the LLM verifier's only job is to decide whether `evidence`
+ * exists, this helper owns the routing once that is known.
+ *
+ *   - A `backstop` (non-inferable) truth with NO explicit evidence → `{ unverified, flagged }`,
+ *     reason `insufficient_spec`. NEVER green — the verify-time companion to D4's never-silent-pass.
+ *   - A `backstop` truth WITH explicit evidence (a passing wired held-out/property test) → `green`.
+ *     Abstention is for the *unconfirmable*, not for every non-inferable check.
+ *   - Any non-`backstop` truth (explicit, or a plain inferable string) → `green`, never flagged.
+ *     This is the over-abstention guard (AC#3): abstention fires ONLY on the exogenous backstop tag.
+ */
+function dispositionForUnverifiableTruth(truth, context = {}) {
+    const tier = truthVerification(truth);
+    // Over-abstention guard (AC#3): only a backstop (non-inferable) truth is ever a candidate to abstain.
+    if (tier !== 'backstop') {
+        return {
+            status: 'green',
+            flagged: false,
+            tier,
+            reason: 'inferable truth — verified normally (no abstention; ADR-550 D4 over-abstention guard)',
+        };
+    }
+    const evidence = Array.isArray(context.evidence) ? context.evidence : [];
+    if (evidence.length === 0) {
+        // ABSTAIN: a non-inferable truth the verifier cannot confirm with explicit evidence. Routes to
+        // human_needed with the distinguishable insufficient_spec reason — never a silent pass (ADR-550 D4).
+        return { status: 'unverified', flagged: true, tier, reason: exports.INSUFFICIENT_SPEC };
+    }
+    return {
+        status: 'green',
+        flagged: false,
+        tier,
+        reason: 'backstop truth confirmed by explicit evidence (a passing wired held-out/property test or directly-observed behavior)',
+    };
+}
 /**
  * Read the requirements file (and optional resolutions file), run the adapter's `analyze`,
  * and write the report as pretty JSON + newline. With no requirements path, writes the usage

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -7,10 +7,19 @@
  *
  * Owns reviewer-selection policy projection for /gsd:review:
  * explicit flags > --all > review.default_reviewers > all detected.
+ *
+ * Reviewer instances (#1517): a bounded config surface
+ * `review.reviewer_instances.<name> = {cli, model?, agent?}` lets one
+ * model-capable adapter (e.g. opencode) run as several independent reviewer
+ * identities. Instances participate ONLY in the config_default branch (no
+ * per-instance CLI flags). An instance is available iff its base `cli` is
+ * detected. The instance→cli mapping lives HERE (single source; see the parity
+ * test in tests/review-reviewer-instances.test.cjs — DEFECT.GENERATIVE-FIX).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_REVIEWER_SLUGS = void 0;
+exports.INSTANCE_NAME_PATTERN = exports.KNOWN_REVIEWER_SLUGS = void 0;
 exports.normalizeConfiguredDefaultReviewers = normalizeConfiguredDefaultReviewers;
+exports.normalizeReviewerInstances = normalizeReviewerInstances;
 exports.resolveReviewerSelection = resolveReviewerSelection;
 exports.KNOWN_REVIEWER_SLUGS = [
     'gemini',
@@ -25,6 +34,8 @@ exports.KNOWN_REVIEWER_SLUGS = [
     'lm_studio',
     'llama_cpp',
 ];
+/** Instance names are lowercase slugs that must not shadow a built-in slug. */
+exports.INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function normalizeConfiguredDefaultReviewers(rawValue) {
     if (rawValue === undefined || rawValue === null) {
         return { absent: true, values: [], errors: [] };
@@ -63,14 +74,75 @@ function normalizeConfiguredDefaultReviewers(rawValue) {
     }
     return { absent: false, values: normalized, errors };
 }
+/**
+ * Validate the `review.reviewer_instances` config object (#1517).
+ * `cli` MUST be a known adapter (never an arbitrary shell command — Kerckhoffs /
+ * Postel: strict at the invocation boundary). `model`/`agent` are opaque
+ * pass-through strings; they are never interpolated into shell strings by this
+ * module. Instance names must not collide with a built-in slug.
+ */
+function normalizeReviewerInstances(rawValue) {
+    if (rawValue === undefined || rawValue === null) {
+        return { instances: {}, errors: [] };
+    }
+    if (typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+        return {
+            instances: {},
+            errors: ['review.reviewer_instances must be a JSON object mapping instance names to {cli,model,agent}'],
+        };
+    }
+    const obj = rawValue;
+    const instances = {};
+    const errors = [];
+    for (const [name, spec] of Object.entries(obj)) {
+        if (!exports.INSTANCE_NAME_PATTERN.test(name)) {
+            errors.push(`invalid reviewer instance name '${name}': must match ^[a-z0-9][a-z0-9-]*$`);
+            continue;
+        }
+        if (exports.KNOWN_REVIEWER_SLUGS.includes(name)) {
+            errors.push(`reviewer instance name '${name}' must not equal a built-in reviewer slug`);
+            continue;
+        }
+        if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+            errors.push(`reviewer_instances.${name} must be an object with at least {cli}`);
+            continue;
+        }
+        const s = spec;
+        const cli = s.cli;
+        if (typeof cli !== 'string' || !exports.KNOWN_REVIEWER_SLUGS.includes(cli)) {
+            errors.push(`reviewer_instances.${name}.cli must be a known reviewer adapter (got: ${JSON.stringify(cli)})`);
+            continue;
+        }
+        const instance = { cli };
+        if (s.model !== undefined && s.model !== null) {
+            if (typeof s.model !== 'string') {
+                errors.push(`reviewer_instances.${name}.model must be a string`);
+                continue;
+            }
+            instance.model = s.model;
+        }
+        if (s.agent !== undefined && s.agent !== null) {
+            if (typeof s.agent !== 'string') {
+                errors.push(`reviewer_instances.${name}.agent must be a string`);
+                continue;
+            }
+            instance.agent = s.agent;
+        }
+        instances[name] = instance;
+    }
+    return { instances, errors };
+}
 function resolveReviewerSelection(input) {
     const detected = new Set((input.detected ?? []).map((v) => String(v).toLowerCase()));
     const explicitFlags = new Set((input.explicitFlags ?? []).map((v) => String(v).toLowerCase()));
     const allFlag = !!input.allFlag;
     const normalizedDefaults = normalizeConfiguredDefaultReviewers(input.configuredDefaultReviewers);
+    const normalizedInstances = normalizeReviewerInstances(input.reviewerInstances);
+    const instances = normalizedInstances.instances;
+    const instancesConfigured = Object.keys(instances).length > 0;
     const warnings = [];
     const infos = [];
-    const errors = [...normalizedDefaults.errors];
+    const errors = [...normalizedDefaults.errors, ...normalizedInstances.errors];
     let source = 'no_config_all_detected';
     let selected = [];
     if (explicitFlags.size > 0) {
@@ -90,20 +162,40 @@ function resolveReviewerSelection(input) {
     }
     else if (!normalizedDefaults.absent) {
         source = 'config_default';
-        const knownDefaults = [];
-        for (const slug of normalizedDefaults.values) {
-            if (!exports.KNOWN_REVIEWER_SLUGS.includes(slug)) {
-                warnings.push(`unknown reviewer slug in review.default_reviewers: ${slug}`);
+        // #1517: expand instance references BEFORE the built-in-slug check. An
+        // instance name and a built-in slug are the two legal kinds of entry.
+        for (const entry of normalizedDefaults.values) {
+            if (instances[entry]) {
+                // Instance reference — available iff its base cli is detected.
+                const cli = instances[entry].cli;
+                if (!detected.has(cli)) {
+                    infos.push(`configured instance ${entry} not detected (cli ${cli} missing on this host)`);
+                }
+                else {
+                    selected.push(entry);
+                }
+            }
+            else if (exports.KNOWN_REVIEWER_SLUGS.includes(entry)) {
+                if (!detected.has(entry)) {
+                    infos.push(`configured reviewers not detected on this host: ${entry}`);
+                }
+                else {
+                    selected.push(entry);
+                }
             }
             else {
-                knownDefaults.push(slug);
+                // Neither a defined instance nor a built-in slug.
+                if (instancesConfigured) {
+                    // Most likely a typo'd instance name — must be loud (#1517 design Q2).
+                    errors.push(`reviewer instance '${entry}' referenced in review.default_reviewers is not defined in review.reviewer_instances`);
+                }
+                else {
+                    // Backward-compatible behaviour: unknown slug with no instances
+                    // configured warns and is dropped.
+                    warnings.push(`unknown reviewer slug in review.default_reviewers: ${entry}`);
+                }
             }
         }
-        const undetected = knownDefaults.filter((slug) => !detected.has(slug));
-        if (undetected.length > 0) {
-            infos.push(`configured reviewers not detected on this host: ${undetected.join(', ')}`);
-        }
-        selected = knownDefaults.filter((slug) => detected.has(slug));
         if (selected.length === 0 && errors.length === 0) {
             errors.push('all configured default reviewers are unavailable on this host');
         }
@@ -111,11 +203,35 @@ function resolveReviewerSelection(input) {
     else {
         selected = [...detected];
     }
+    const selectedSorted = selected.sort();
+    // Single-source instance→cli resolution projected onto the selected set.
+    const resolvedInstances = selectedSorted.map((identity) => {
+        const inst = instances[identity];
+        if (inst) {
+            return {
+                identity,
+                kind: 'instance',
+                cli: inst.cli,
+                model: inst.model,
+                agent: inst.agent,
+            };
+        }
+        return { identity, kind: 'builtin', cli: identity };
+    });
+    const cliCounts = {};
+    for (const r of resolvedInstances) {
+        if (r.kind === 'instance') {
+            cliCounts[r.cli] = (cliCounts[r.cli] ?? 0) + 1;
+        }
+    }
+    const sharedAdapterCaveat = Object.values(cliCounts).some((c) => c >= 2);
     return {
         source,
-        selected: selected.sort(),
+        selected: selectedSorted,
         warnings,
         infos,
         errors,
+        resolvedInstances,
+        sharedAdapterCaveat,
     };
 }

package/gsd-core/bin/lib/roadmap-upgrade.cjs

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+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");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -416,7 +417,7 @@ function applyMigration(cwd, plan, options = {}) {
             const oldPath = node_path_1.default.join(phasesDir, phaseEntry.oldDir);
             const newPath = node_path_1.default.join(phasesDir, phaseEntry.newDir);
             if (node_fs_1.default.existsSync(oldPath)) {
-                node_fs_1.default.renameSync(oldPath, newPath);
+                (0, shell_command_projection_cjs_1.retryRenameSync)(oldPath, newPath);
                 performedRenames.push({ oldPath, newPath });
                 renamedDirs.push(`${phaseEntry.oldDir} → ${phaseEntry.newDir}`);
             }
@@ -483,7 +484,7 @@ function applyMigration(cwd, plan, options = {}) {
             const { oldPath, newPath } = performedRenames[i];
             try {
                 if (node_fs_1.default.existsSync(newPath))
-                    node_fs_1.default.renameSync(newPath, oldPath);
+                    (0, shell_command_projection_cjs_1.retryRenameSync)(newPath, oldPath);
             }
             catch { /* best-effort */ }
         }

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

@@ -55,8 +55,11 @@ function coerceTruthToString(t) {
         return String(t);
     }
     if (typeof t === 'object') {
-        // Prefer common title-bearing keys produced by parseMustHavesBlock
-        for (const k of ['title', 'text', 'name', 'rule', 'path', 'provides']) {
+        // Prefer common title-bearing keys produced by parseMustHavesBlock. `statement` is the canonical
+        // truth/prohibition payload field — and the carrier of #1154's object-form backstop truth
+        // `{ statement, verification: backstop }`, so it leads (a non-inferable truth must be coerced by
+        // its statement, never dropped — the Hyrum backward-compat guard for the new marker).
+        for (const k of ['statement', 'title', 'text', 'name', 'rule', 'path', 'provides']) {
             const v = t[k];
             if (typeof v === 'string' && v.trim())
                 return v;
@@ -249,6 +252,15 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)\s*:\s*([^\n]+)/gi;
     const phases = [];
     let match;
+    // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not real
+    // phases. They legitimately have no directory and must never be surfaced as
+    // current/next phase or counted in phase_count. Mirrors the engine-wide
+    // sentinel convention (phase-id getMilestoneFromPhaseId, roadmap-command-router
+    // SENTINELS, the #1445 /^999/ progress filters). (#1580)
+    const isSentinelPhase = (num) => {
+        const major = parseInt(num, 10);
+        return major === 0 || major === 999;
+    };
     // Build phase directory lookup once (O(1) readdir instead of O(N) per phase)
     const _phaseDirNames = (() => {
         try {
@@ -262,6 +274,8 @@ function cmdRoadmapAnalyze(cwd, raw) {
     })();
     while ((match = phasePattern.exec(content)) !== null) {
         const phaseNum = match[1];
+        if (isSentinelPhase(phaseNum))
+            continue;
         const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim();
         // Extract goal from the section
         const sectionStart = match.index;
@@ -362,7 +376,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
         checklistPhases.add(checklistMatch[1]);
     }
     const detailPhases = new Set(phases.map(p => p.number));
-    const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p));
+    const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p) && !isSentinelPhase(p));
     const result = {
         milestones,
         phases,

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -25,6 +25,7 @@ const commandRoster = require("./command-roster.cjs");
 const { readGsdCommandNames, transformContentToHyphen } = commandRoster;
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const { getDirName } = runtimeNamePolicy;
+const capabilityRegistry = require("./capability-registry.cjs");
 // #1383: resolve GSD's version WITHOUT a top-level
 // `require('../../../package.json')`. That require ran at module load on every
 // gsd-tools invocation (this module sits in the gsd-tools loader chain) and
@@ -1997,16 +1998,15 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
 }
 /**
  * Canonical list of every non-Claude runtime that gsd-core emits artifacts for.
- * Exported so test files can import this single source of truth rather than
- * maintaining divergent hand-rolled arrays (#1521).
- *
- * Keep in sync with the runtime flags in bin/install.js and getDirName().
+ * DERIVED from the capability registry (ADR-1239 Phase B, #1679) — the registry's
+ * `runtimes` map is the single source of truth for runtime identity, so the
+ * non-Claude set is its key set minus 'claude'. This replaces a hand-maintained
+ * literal that had to be kept in sync with bin/install.js and getDirName(), and
+ * can no longer drift from the registry. Exported so tests import one source (#1521).
  */
-const NON_CLAUDE_RUNTIMES = [
-    'codex', 'opencode', 'kilo', 'gemini', 'copilot', 'antigravity',
-    'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'kimi',
-    'codebuddy', 'cline',
-];
+const NON_CLAUDE_RUNTIMES = Object.keys(capabilityRegistry.runtimes)
+    .filter((id) => id !== 'claude')
+    .sort();
 /**
  * #1521: Every non-Claude runtime resolves its own runtime identity from a
  * runtime-neutral config, and defaults workflow.use_worktrees to false —
@@ -2310,6 +2310,59 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
     return applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix, isGlobal, attribution);
 }
+/**
+ * Runtimes that use the hyphen-namespace form `/gsd-<cmd>` in agent bodies.
+ * claude/qwen/hermes use hyphen-name:`...` frontmatter; cursor/windsurf/etc
+ * self-convert. Mirrors the `HYPHEN_NAME_AGENT_RUNTIMES` set in bin/install.js.
+ *
+ * @private — export normalizeAgentBodyForRuntime for callers.
+ */
+const HYPHEN_NAME_AGENT_RUNTIMES = new Set(['claude', 'qwen', 'hermes']);
+/**
+ * Normalize `/gsd:<cmd>` colon refs in the agent body to `/gsd-<cmd>` for
+ * hyphen-`name:` runtimes (claude / qwen / hermes). No-op for all other
+ * runtimes. Mirrors the per-file call in bin/install.js line 9400.
+ *
+ * @param content   raw agent file content (post-converter)
+ * @param runtime   canonical runtime ID
+ * @param cmdNames  gsd command names from readGsdCommandNames()
+ */
+function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
+    if (!HYPHEN_NAME_AGENT_RUNTIMES.has(runtime))
+        return content;
+    return transformContentToHyphen(content, cmdNames);
+}
+/**
+ * Apply the 4 base `~/.claude/` path-prefix rewrites to a single agent content
+ * string. Mirrors the inline agent loop in bin/install.js lines 9330-9340:
+ *   ~/\.claude/ → pathPrefix
+ *   $HOME/\.claude/ → pathPrefix
+ *   ~/\.claude\b → normalizedPathPrefix
+ *   $HOME/\.claude\b → normalizedPathPrefix
+ *
+ * Skipped for copilot and antigravity (which do NOT do path rewrites in the
+ * inline loop). NO stamp (_stampNonClaudeRuntimeDefaults) — agents are NOT
+ * stamped in the inline loop.
+ *
+ * ADR-1235 §1: pre-converter cross-cutting for descriptor-driven agent pipeline.
+ * Exported as `applyAgentPathRewrites` for testing and for injection into
+ * stageAgentsForRuntimeWithConverter via agentCtx.
+ *
+ * @param content     raw agent file content
+ * @param runtime     canonical runtime ID
+ * @param pathPrefix  trailing-slash path prefix (e.g. '$HOME/.cursor/')
+ * @returns content with path-prefix rewrites applied (or unchanged for copilot/antigravity)
+ */
+function applyAgentPathRewrites(content, runtime, pathPrefix) {
+    if (runtime === 'copilot' || runtime === 'antigravity')
+        return content;
+    const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
+    content = content.replace(/~\/\.claude\//g, pathPrefix);
+    content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
+    content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
+    content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
+    return content;
+}
 // ── End rewrite engine ────────────────────────────────────────────────────────
 /**
  * Apply Co-Authored-By attribution policy to file content.
@@ -2398,6 +2451,9 @@ module.exports = {
     // High-level wrappers (derive pathPrefix + attribution from opts):
     rewriteStagedSkillBodies,
     rewriteStagedCommandBodies,
+    // ADR-1235 §1: descriptor-driven agent cross-cutting
+    applyAgentPathRewrites,
+    normalizeAgentBodyForRuntime,
     _computePathPrefix: computePathPrefix,
     _applyRuntimeRewrites,
     _stampNonClaudeRuntimeDefaults,

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -9,6 +9,30 @@
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 const path = _require('node:path');
+/**
+ * Asserts that `destSubpath` resolves to a path inside `configDir`.
+ *
+ * Rejects any path that escapes the configDir root (e.g. "../../etc") and any
+ * path containing a NUL byte. This is a security gate for Phase B of
+ * ADR-1239: third-party descriptors must never be able to write outside the
+ * designated config home directory.
+ *
+ * @param configDir - The root config directory (e.g. ~/.claude).
+ * @param destSubpath - The relative path declared by the runtime descriptor.
+ * @returns The resolved absolute path under configDir.
+ * @throws {Error} if destSubpath escapes configDir or contains a NUL byte.
+ */
+function assertDestWithinConfigHome(configDir, destSubpath) {
+    if (destSubpath.includes('\0')) {
+        throw new Error(`destSubpath "${destSubpath}" contains a NUL byte and is not valid`);
+    }
+    const root = path.resolve(configDir);
+    const resolved = path.resolve(configDir, destSubpath);
+    if (resolved === root || !resolved.startsWith(root + path.sep)) {
+        throw new Error(`destSubpath "${destSubpath}" must be a strict subpath of configHome "${configDir}" — not configHome itself or outside it (escapes configHome)`);
+    }
+    return resolved;
+}
 function errorMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -36,10 +60,34 @@ function createRuntimeArtifactInstallPlan(args) {
         platform,
         resolveAttribution,
     };
+    // ADR-1235 §1: build agentCtx once per plan so agents kind entries can apply
+    // the CORRECT pre-converter cross-cutting (path rewrites → attribution → converter
+    // → normalize). This mirrors the exact per-file order in the inline agent loop
+    // in bin/install.js (lines 9330-9415). agentCtx is passed as the second arg
+    // to kind.stage() for agents kind entries with a converter (convertedAgentsKind).
+    // NO _stampNonClaudeRuntimeDefaults — agents are NOT stamped in the inline loop.
+    const os = _require('node:os');
+    const homedirFn = homedir ?? (() => os.homedir());
+    const resolvedTarget = path.resolve(layout.configDir).replace(/\\/g, '/');
+    const homeDir = homedirFn().replace(/\\/g, '/');
+    const isGlobal = scope === 'global';
+    const isOpencode = layout.runtime === 'opencode';
+    const isWindowsHost = (platform ?? process.platform) === 'win32';
+    const pathPrefix = conversionExports._computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
+    const attribution = resolveAttribution ? resolveAttribution(layout.runtime) : undefined;
+    const agentCtx = { runtime: layout.runtime, pathPrefix, attribution };
     for (const kind of layout.kinds) {
         let stagedDir;
         try {
-            stagedDir = kind.stage(resolvedProfile);
+            if (kind.kind === 'agents') {
+                // ADR-1235 §1: pass agentCtx so stageAgentsForRuntimeWithConverter applies
+                // the full inline-loop order: pathRewrites → attribution → converter → normalize.
+                // The cross-cutting is now PRE-converter (inside staging), not POST.
+                stagedDir = kind.stage(resolvedProfile, agentCtx);
+            }
+            else {
+                stagedDir = kind.stage(resolvedProfile);
+            }
         }
         catch (err) {
             return { ok: false, kind: 'stage_failed', message: errorMessage(err), cleanupDirs, failedKind: kind.kind };
@@ -54,6 +102,8 @@ function createRuntimeArtifactInstallPlan(args) {
                 const rewrittenDir = rewriteStagedSkillBodies(stagedDir, rewriteOpts);
                 sourceDir = addCleanupDir(cleanupDirs, stagedDir, rewrittenDir);
             }
+            // agents kind: cross-cutting already applied INSIDE kind.stage() via agentCtx.
+            // No POST-step needed. sourceDir stays as stagedDir.
         }
         catch (err) {
             return { ok: false, kind: 'rewrite_failed', message: errorMessage(err), cleanupDirs, failedKind: kind.kind };
@@ -61,7 +111,7 @@ function createRuntimeArtifactInstallPlan(args) {
         items.push({
             kind: kind.kind,
             sourceDir,
-            destDir: path.join(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
         });
     }
     return { ok: true, plan: { items, cleanupDirs } };
@@ -70,8 +120,8 @@ function createRuntimeArtifactUninstallPlan(layout) {
     return {
         items: layout.kinds.map((kind) => ({
             kind: kind.kind,
-            destDir: path.join(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
         })),
     };
 }
-module.exports = { createRuntimeArtifactInstallPlan, createRuntimeArtifactUninstallPlan };
+module.exports = { assertDestWithinConfigHome, createRuntimeArtifactInstallPlan, createRuntimeArtifactUninstallPlan };

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -156,13 +156,16 @@ function convertedAgentsKind(destSubpath, prefix, converterName, configDir, scop
         kind: 'agents',
         destSubpath,
         prefix,
-        stage: (resolved) => {
+        stage: (resolved, agentCtx) => {
             // isGlobal is threaded so scope-aware agent converters (copilot, antigravity)
             // choose global-home vs workspace-relative paths; converters that only take
             // (content) ignore the extra positional arg. Mirrors skillsKind's scope
             // threading (#1173).
             const converter = conversionExports[converterName];
-            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter, scope === 'global');
+            // ADR-1235 §1: when agentCtx is provided (by createRuntimeArtifactInstallPlan
+            // for descriptor-driven runtimes), thread it through so stageAgentsForRuntimeWithConverter
+            // can apply the full pre-converter + post-converter sequence in the correct order.
+            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter, scope === 'global', agentCtx);
         },
     };
 }

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -84,7 +84,7 @@ function atomicWriteFileSync(target, data, options) {
     __atomicWrittenTmps.add(tmp);
     try {
         node_fs_1.default.writeFileSync(tmp, data, options);
-        node_fs_1.default.renameSync(tmp, target);
+        shellCmdProjection.retryRenameSync(tmp, target);
         // Successful rename: the tmp path no longer exists, but leave it in the
         // Set so _cleanTmpFiles can recognise it as installer-owned if it somehow
         // lingers (e.g. a rename succeeded but left a stale entry on some FS).