@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/prompt-budget.cjs

@@ -10,7 +10,12 @@
  *
  * Used by the review pipeline to support small-context models.
  *
- * Trim priority (in order — never violate):
+ * Trim priority (in order — never violate). As of #2929 (epic #1671 Phase 2)
+ * the ladder itself is executed by the shared `context-composer` seam
+ * (`composeWithinBudget`); this module builds the fragment list in this
+ * exact order, delegates the decision of what survives/shrinks/truncates,
+ * and keeps only the prompt-specific rendering (`renderNote`,
+ * `assemblePrompt`) and the hard-fail response shapes here:
  *   1. Instructions:   ALWAYS kept verbatim
  *   2. Reserve note tokens FIRST when any trim is anticipated
  *   3. Roadmap:        ALWAYS kept verbatim
@@ -22,9 +27,20 @@
  *   9. Hard-fail:      if minimum-set exceeds effectiveBudget
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_FLOOR_CHARS = void 0;
 exports.estimateTokens = estimateTokens;
+exports.buildBudgetFragments = buildBudgetFragments;
 exports.applyBudget = applyBudget;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- context-composer.cjs is an export= CommonJS module
+const contextComposer = require("./context-composer.cjs");
 const NOTE_RESERVE_TOKENS = 80;
+/**
+ * Floor per plan when proportionally truncating and for the minimum-set
+ * check. Exported so consumers (notably the load-bearing contract gate,
+ * issue #3065) never need to re-declare this value locally.
+ */
+exports.PLAN_FLOOR_CHARS = 1024;
+const MIN_PLAN_BYTES = exports.PLAN_FLOOR_CHARS;
 const DEFAULT_NOTE_TEMPLATE = [
     '<note>',
     'Prompt automatically trimmed to fit a {budget}-token budget.',
@@ -51,30 +67,6 @@ function renderNote(template, budget, omitted, planTruncationPct) {
         .replace('{omittedList}', omittedList)
         .replace('{planTruncationPct}', String(Math.round(planTruncationPct)));
 }
-/**
- * Head-shrink a string to at most `maxLines` lines.
- */
-function headShrink(text, maxLines) {
-    if (maxLines <= 0)
-        return '';
-    let idx = -1;
-    let seen = 0;
-    while (seen < maxLines) {
-        idx = text.indexOf('\n', idx + 1);
-        if (idx === -1)
-            return text;
-        seen += 1;
-    }
-    return text.slice(0, idx);
-}
-/**
- * Tail-truncate a string to at most `maxChars` characters.
- */
-function tailTruncate(text, maxChars) {
-    if (text.length <= maxChars)
-        return text;
-    return text.slice(0, maxChars);
-}
 /**
  * Assemble the final prompt string from its sections.
  */
@@ -99,38 +91,92 @@ function assemblePrompt(parts) {
         blocks.push('## Requirements\n\n' + requirements);
     return blocks.join('\n\n');
 }
+/**
+ * Build the `composeWithinBudget` fragment array for a set of review prompt
+ * sections, with each fragment's declared trim strategy attached.
+ *
+ * Extracted (issue #3065) so the load-bearing contract gate
+ * (tests/load-bearing-contract-gate.test.cjs) can assert directly over the
+ * REAL declared strategies used by `applyBudget`, rather than a hand-copied
+ * duplicate array. A duplicate would let production silently diverge from
+ * the gate (e.g. flipping `roadmap` from `verbatim` to `drop` would keep the
+ * gate green if it read from a copy) — exactly the
+ * `DEFECT.GENERATIVE-FIX` divergence class this extraction exists to
+ * prevent. Pure; performs no I/O and has no side effects.
+ */
+function buildBudgetFragments(sections, projectMdHeadLines) {
+    const { instructions, roadmap, plans, projectMd: projectMdRaw = null, context: contextRaw = null, research: researchRaw = null, requirements: requirementsRaw = null, } = sections;
+    // Unique per-plan fragment ids: plain `plan:<file>` unless a filename
+    // collision forces disambiguation by index — composeWithinBudget throws on
+    // duplicate ids, and legitimate input may repeat a filename across plans.
+    const usedPlanIds = new Set();
+    const planIds = plans.map((p, idx) => {
+        let id = `plan:${p.file}`;
+        if (usedPlanIds.has(id))
+            id = `plan:${idx}:${p.file}`;
+        usedPlanIds.add(id);
+        return id;
+    });
+    const planFragments = plans.map((p, idx) => ({
+        id: planIds[idx],
+        content: p.content,
+        wrapper: `### ${p.file}\n\n`,
+        strategy: { kind: 'proportional-truncate', floorChars: MIN_PLAN_BYTES },
+        group: 'plans',
+        required: true,
+    }));
+    return [
+        { id: 'instructions', content: instructions, wrapper: '', strategy: { kind: 'verbatim' }, required: true },
+        { id: 'roadmap', content: roadmap, wrapper: '## Roadmap\n\n', strategy: { kind: 'verbatim' }, required: true },
+        {
+            id: 'projectMd',
+            content: projectMdRaw ?? '',
+            wrapper: '## Project\n\n',
+            strategy: { kind: 'head-shrink', maxLines: projectMdHeadLines },
+        },
+        { id: 'plans-header', content: '', wrapper: '## Plans\n\n', strategy: { kind: 'verbatim' }, required: true },
+        ...planFragments,
+        { id: 'context', content: contextRaw ?? '', wrapper: '## Context\n\n', strategy: { kind: 'drop' } },
+        { id: 'research', content: researchRaw ?? '', wrapper: '## Research\n\n', strategy: { kind: 'drop' } },
+        { id: 'requirements', content: requirementsRaw ?? '', wrapper: '## Requirements\n\n', strategy: { kind: 'drop' } },
+    ];
+}
 /**
  * Apply a token budget to a set of review prompt sections.
  * Returns the trimmed prompt and structured metadata.
  */
 function applyBudget({ sections, budget, options = {} }) {
     const { safetyMarginPct = 10, noteTemplate = DEFAULT_NOTE_TEMPLATE, projectMdHeadLines = 40, } = options;
-    const effectiveBudget = Math.floor(budget * (1 - safetyMarginPct / 100));
-    const { instructions, roadmap, plans, projectMd: projectMdRaw = null, context: contextRaw = null, research: researchRaw = null, requirements: requirementsRaw = null, } = sections;
-    // Working mutable state
-    let projectMd = projectMdRaw;
-    let context = contextRaw;
-    let research = researchRaw;
-    let requirements = requirementsRaw;
-    let workingPlans = plans.map((p) => ({ file: p.file, content: p.content }));
-    const omitted = [];
-    let projectMdShrunk = false;
-    let planTruncationPct = 0;
-    let noteInjected = false;
-    let hardFailed = false;
-    // Minimum-set check: instructions + roadmap + 1KB per plan.
-    // NOTE_RESERVE_TOKENS is intentionally excluded here: a note is only injected
-    // when trimming actually occurs, and a prompt that fits without any trim needs
-    // no note at all. Including NOTE_RESERVE_TOKENS here would cause false hard-fails
-    // for prompts that genuinely fit the effective budget untrimmed.
-    const MIN_PLAN_BYTES = 1024;
-    const minPlanTokens = plans.reduce((sum, p) => {
-        return sum + estimateTokens(p.content.slice(0, MIN_PLAN_BYTES));
-    }, 0);
-    const minSet = estimateTokens(instructions) +
-        estimateTokens(roadmap) +
-        minPlanTokens;
-    if (minSet > effectiveBudget) {
+    const { plans } = sections;
+    const fragments = buildBudgetFragments(sections, projectMdHeadLines);
+    // Recover the per-plan fragment ids buildBudgetFragments assigned (in
+    // `plans` declaration order) rather than re-deriving the id-collision
+    // logic here — a single source of truth for id assignment.
+    const planIds = fragments.filter((f) => f.group === 'plans').map((f) => f.id);
+    const composed = contextComposer.composeWithinBudget({
+        fragments,
+        budget,
+        measure: estimateTokens,
+        options: {
+            safetyMarginPct,
+            reserve: NOTE_RESERVE_TOKENS,
+            charsPerUnit: 4,
+            // Minimum-set floor: instructions + roadmap (in full) + 1KB per plan.
+            // NOTE_RESERVE_TOKENS is intentionally excluded — a note is only
+            // injected when trimming actually occurs, and a prompt that fits
+            // without any trim needs no note at all. Wrappers are also excluded
+            // (this checks the floor, not the steady-state budget).
+            minimumFor: (f) => {
+                if (f.id === 'instructions' || f.id === 'roadmap')
+                    return f.content;
+                if (f.id.startsWith('plan:'))
+                    return f.content.slice(0, MIN_PLAN_BYTES);
+                return null;
+            },
+        },
+    });
+    const effectiveBudget = composed.metadata.effectiveBudget;
+    if (composed.metadata.hardFailed) {
         return {
             prompt: '',
             metadata: {
@@ -145,127 +191,45 @@ function applyBudget({ sections, budget, options = {} }) {
             },
         };
     }
-    // ── Budget accounting ──────────────────────────────────────────────────────
-    const TOKENS_ROADMAP_HEADER = estimateTokens('## Roadmap\n\n');
-    const TOKENS_PROJECT_HEADER = estimateTokens('## Project\n\n');
-    const TOKENS_PLANS_HEADER = estimateTokens('## Plans\n\n');
-    const TOKENS_CONTEXT_HEADER = estimateTokens('## Context\n\n');
-    const TOKENS_RESEARCH_HEADER = estimateTokens('## Research\n\n');
-    const TOKENS_REQUIREMENTS_HEADER = estimateTokens('## Requirements\n\n');
-    const TOKENS_PLAN_ITEM_HEADERS = workingPlans.reduce((sum, p) => sum + estimateTokens('### ' + p.file + '\n\n'), 0);
-    const staticBaseTokens = estimateTokens(instructions) +
-        TOKENS_ROADMAP_HEADER +
-        estimateTokens(roadmap) +
-        TOKENS_PLANS_HEADER +
-        TOKENS_PLAN_ITEM_HEADERS;
-    let projectTokens = projectMd
-        ? TOKENS_PROJECT_HEADER + estimateTokens(projectMd)
-        : 0;
-    let contextTokens = context
-        ? TOKENS_CONTEXT_HEADER + estimateTokens(context)
-        : 0;
-    let researchTokens = research
-        ? TOKENS_RESEARCH_HEADER + estimateTokens(research)
-        : 0;
-    let requirementsTokens = requirements
-        ? TOKENS_REQUIREMENTS_HEADER + estimateTokens(requirements)
-        : 0;
-    let planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
-    const getCurrentBaseTokens = () => staticBaseTokens +
-        projectTokens +
-        planContentTokens +
-        contextTokens +
-        researchTokens +
-        requirementsTokens;
-    let currentBaseTokens = getCurrentBaseTokens();
-    // Detect budget pressure: is ANY trim needed?
-    // Pressure exists when the current base tokens already exceed the effective
-    // budget. Only when pressure is real do we reserve NOTE_RESERVE_TOKENS so
-    // the note itself fits after trimming. Checking against
-    // effectiveBudget - NOTE_RESERVE_TOKENS (the old threshold) would cause
-    // spurious pressure 80 tokens early, dropping sections that fit fine.
-    const baseTokens = currentBaseTokens;
-    const budgetUnderPressure = baseTokens > effectiveBudget;
-    // Available for content (reserve note slot when under pressure)
-    const contentBudget = budgetUnderPressure
-        ? effectiveBudget - NOTE_RESERVE_TOKENS
-        : effectiveBudget;
-    // ── Trim step 1: head-shrink PROJECT.md ───────────────────────────────────
-    if (currentBaseTokens > contentBudget && projectMd) {
-        const shrunk = headShrink(projectMd, projectMdHeadLines);
-        if (shrunk !== projectMd) {
-            projectMd = shrunk;
-            projectMdShrunk = true;
-            projectTokens = TOKENS_PROJECT_HEADER + estimateTokens(projectMd);
-            currentBaseTokens = getCurrentBaseTokens();
-        }
-    }
-    // ── Trim step 2: proportional plan truncation ─────────────────────────────
-    if (currentBaseTokens > contentBudget) {
-        // Compute tokens available for plan content only
-        const overhead = staticBaseTokens +
-            projectTokens +
-            contextTokens +
-            researchTokens +
-            requirementsTokens;
-        const planBudgetTokens = contentBudget - overhead;
-        const totalPlanTokens = planContentTokens;
-        if (planBudgetTokens > 0 && planBudgetTokens < totalPlanTokens) {
-            // Proportional share per plan (at least 1KB per plan)
-            const totalOriginalChars = plans.reduce((sum, p) => sum + p.content.length, 0);
-            const totalPlanCharsBudget = planBudgetTokens * 4;
-            workingPlans = workingPlans.map((p) => {
-                const proportionalShare = totalOriginalChars > 0
-                    ? Math.floor((p.content.length / totalOriginalChars) * totalPlanCharsBudget)
-                    : 0;
-                const maxChars = Math.max(proportionalShare, MIN_PLAN_BYTES);
-                return { file: p.file, content: tailTruncate(p.content, maxChars) };
-            });
-            const newTotalChars = workingPlans.reduce((sum, p) => sum + p.content.length, 0);
-            if (totalOriginalChars > 0) {
-                planTruncationPct =
-                    ((totalOriginalChars - newTotalChars) / totalOriginalChars) * 100;
-            }
-            planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
-            currentBaseTokens = getCurrentBaseTokens();
-        }
-    }
-    // ── Trim step 3: drop context ─────────────────────────────────────────────
-    if (currentBaseTokens > contentBudget && context) {
-        context = null;
-        omitted.push('context');
-        contextTokens = 0;
-        currentBaseTokens = getCurrentBaseTokens();
-    }
-    // ── Trim step 4: drop research ────────────────────────────────────────────
-    if (currentBaseTokens > contentBudget && research) {
-        research = null;
-        omitted.push('research');
-        researchTokens = 0;
-        currentBaseTokens = getCurrentBaseTokens();
-    }
-    // ── Trim step 5: drop requirements (last resort) ──────────────────────────
-    if (currentBaseTokens > contentBudget && requirements) {
-        requirements = null;
-        omitted.push('requirements');
-        requirementsTokens = 0;
-        currentBaseTokens = getCurrentBaseTokens();
-    }
+    const byId = new Map(composed.fragments.map((f) => [f.id, f]));
+    const get = (id) => {
+        const found = byId.get(id);
+        if (!found)
+            throw new Error(`applyBudget: missing composed fragment "${id}"`);
+        return found;
+    };
+    const instructionsOut = get('instructions').content;
+    const roadmapOut = get('roadmap').content;
+    const projectMdFragment = get('projectMd');
+    const projectMd = projectMdFragment.present ? projectMdFragment.content : null;
+    const contextFragment = get('context');
+    const context = contextFragment.present ? contextFragment.content : null;
+    const researchFragment = get('research');
+    const research = researchFragment.present ? researchFragment.content : null;
+    const requirementsFragment = get('requirements');
+    const requirements = requirementsFragment.present ? requirementsFragment.content : null;
+    // Plans are never dropped — only their content may be truncated — so map
+    // deliberately by original index/file rather than relying on `present`.
+    const workingPlans = plans.map((p, idx) => ({
+        file: p.file,
+        content: get(planIds[idx]).content,
+    }));
+    const omitted = composed.metadata.omitted;
+    const projectMdShrunk = composed.metadata.shrunk.includes('projectMd');
+    const planTruncationPct = composed.metadata.truncationPct;
     // ── Decide whether note is actually needed ────────────────────────────────
     const anyTrimOccurred = omitted.length > 0 || projectMdShrunk || planTruncationPct > 0;
     let note = null;
+    let noteInjected = false;
     if (anyTrimOccurred) {
         note = renderNote(noteTemplate, budget, omitted, planTruncationPct);
         noteInjected = true;
     }
-    // Suppress unused variable warning — currentBaseTokens is used via the
-    // closure in getCurrentBaseTokens(); the final value is not used directly.
-    void currentBaseTokens;
     // ── Assemble ──────────────────────────────────────────────────────────────
     const prompt = assemblePrompt({
-        instructions,
+        instructions: instructionsOut,
         note,
-        roadmap,
+        roadmap: roadmapOut,
         projectMd,
         plans: workingPlans,
         context,
@@ -274,7 +238,6 @@ function applyBudget({ sections, budget, options = {} }) {
     });
     const estimatedTokens = estimateTokens(prompt);
     if (estimatedTokens > effectiveBudget) {
-        hardFailed = true;
         return {
             prompt: '',
             metadata: {
@@ -284,7 +247,7 @@ function applyBudget({ sections, budget, options = {} }) {
                 omitted,
                 projectMdShrunk,
                 planTruncationPct,
-                hardFailed,
+                hardFailed: true,
                 noteInjected,
             },
         };
@@ -298,7 +261,7 @@ function applyBudget({ sections, budget, options = {} }) {
             omitted,
             projectMdShrunk,
             planTruncationPct,
-            hardFailed,
+            hardFailed: false,
             noteInjected,
         },
     };

package/gsd-core/bin/lib/retired-artifact-cleanup.cjs

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Conservative cleanup for artifact surfaces retired by a runtime descriptor.
+ *
+ * A descriptor may stop materializing an artifact kind while old installs
+ * still contain files from that surface. Install and profile/surface apply
+ * both call this helper so either path converges an existing installation.
+ * Only files proven managed by the previous install manifest are removed;
+ * modified and unknown files are preserved for the journaled installer
+ * migration (or the user) to handle without data loss.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installerMigrations = require("./installer-migrations.cjs");
+const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
+// Generated at build time, so no TypeScript source declaration exists.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityRegistry = require('./capability-registry.cjs');
+function retiredArtifactsFor(runtime) {
+    const configured = capabilityRegistry.runtimes?.[runtime]?.runtime?.hostBehaviors?.retiredArtifacts;
+    return Array.isArray(configured) ? configured : [];
+}
+function pruneRetiredRuntimeArtifacts(runtime, configDir) {
+    const result = { removed: [], preserved: [] };
+    const declarations = retiredArtifactsFor(runtime);
+    if (declarations.length === 0)
+        return result;
+    const manifest = installerMigrations.readInstallManifest(configDir);
+    for (const declaration of declarations) {
+        const destSubpath = declaration.destSubpath;
+        const prefix = declaration.prefix;
+        const suffix = declaration.suffix;
+        if (typeof destSubpath !== 'string' || destSubpath.length === 0 ||
+            typeof prefix !== 'string' || prefix.length === 0 ||
+            typeof suffix !== 'string' || suffix.length === 0 ||
+            !(0, external_descriptor_trust_cjs_1.isPathConfined)(destSubpath, configDir)) {
+            continue;
+        }
+        const destDir = node_path_1.default.resolve(configDir, destSubpath);
+        let entries;
+        try {
+            if (!node_fs_1.default.existsSync(destDir) || node_fs_1.default.lstatSync(destDir).isSymbolicLink())
+                continue;
+            entries = node_fs_1.default.readdirSync(destDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith(suffix))
+                continue;
+            const relPath = node_path_1.default.posix.join(destSubpath.replace(/\\/g, '/'), entry.name);
+            const artifact = installerMigrations.classifyArtifact(configDir, relPath, manifest);
+            if (artifact.classification !== 'managed-pristine') {
+                result.preserved.push(relPath);
+                continue;
+            }
+            try {
+                node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, entry.name));
+                result.removed.push(relPath);
+            }
+            catch {
+                result.preserved.push(relPath);
+            }
+        }
+        try {
+            if (node_fs_1.default.readdirSync(destDir).length === 0)
+                node_fs_1.default.rmdirSync(destDir);
+        }
+        catch {
+            // Non-empty, unreadable, or concurrently changed: preserve the directory.
+        }
+    }
+    return result;
+}
+module.exports = { pruneRetiredRuntimeArtifacts, retiredArtifactsFor };

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -52,6 +52,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DOCS_PARITY_VIOLATION = exports.LANE_SLUG_RE = exports.PARITY_VIOLATION = exports.REVIEWER_LANES = exports.ARGV_PLACEHOLDER = void 0;
+exports.mergeReviewerLanes = mergeReviewerLanes;
 exports.checkReviewerLaneParity = checkReviewerLaneParity;
 exports.checkReviewerDocsParity = checkReviewerDocsParity;
 /**
@@ -423,6 +424,104 @@ exports.REVIEWER_LANES = Object.freeze([
         handler: null,
     },
 ].map((lane) => Object.freeze(lane)));
+/**
+ * Merge the first-party lane set with installed overlay `reviewer` bodies
+ * (ADR-2782 D8: first-party ∪ overlay, first-party wins on slug collision).
+ *
+ * `routeReviewLane` (gsd-core/bin/gsd-tools.cjs) consumes this to build the lane
+ * map its `sections`/`flags`/`plan`/`invoke` subcommands resolve against, so an
+ * installed, consented third-party reviewer capability (`role:"reviewer"` with a
+ * declared `reviewer` body) becomes selectable, plannable, and invocable through
+ * the same surface as a built-in lane — closing #2927, where the overlay was
+ * roster-visible (`deriveReviewerSlugs`) and disclosed at install
+ * (`collectReviewerLaneSurfaces`) but never reached the invocation path.
+ *
+ * ADR-2782 D1 deliberately made the manifest `reviewer` body field-identical to
+ * `ReviewerLaneCommon` so "Phase 2 harvests the shape into the capability manifest
+ * with no translation layer" (CONTEXT.md reviewer-lane-descriptor predicate). The
+ * overlay body IS already `ReviewerLane`-shaped; this function MERGES, it does not
+ * PROJECT — there is no field renaming, no vocabulary translation. That is the
+ * design decision the bug violated by simply never calling anything.
+ *
+ * Pure and TOTAL — never throws on any input, because third-party overlay
+ * manifests are untrusted data reaching this seam at load time. A cap whose
+ * `reviewer` body is absent, non-object, or carries an empty/grammar-invalid slug
+ * is SKIPPED (contributes no lane) rather than crashing, so one malformed overlay
+ * cannot take the whole `review-lane` surface (and every first-party lane with it)
+ * down. The slug grammar (`LANE_SLUG_RE`) is enforced HERE even though
+ * `resolveLanePlan`'s trust boundary re-checks it, because `sections`/`flags` read
+ * lane fields before reaching `resolveLanePlan` — defense in depth against the
+ * path-traversal class the invocation boundary exists for.
+ *
+ * First-party wins: an overlay declaring a slug that already names a first-party
+ * lane is silently superseded (the first-party entry is kept, identity-stable),
+ * never overwritten. The first-party object is returned by reference, not copied.
+ *
+ * @param firstParty The frozen first-party lane set (`REVIEWER_LANES`).
+ * @param registry   The merged capability registry
+ *                   (`loadRegistry({ includeInstalled: true })`); only its
+ *                   `capabilities` map is read. A cap contributes a lane iff it
+ *                   carries an object `reviewer` body with a non-empty,
+ *                   grammar-valid `slug`. The `role:"runtime"` legacy
+ *                   `reviewerCli` alias contributes NO lane here — it has no lane
+ *                   descriptor, and the selection roster (`deriveReviewerSlugs`)
+ *                   is a separate surface.
+ * @returns A NEW array: first-party lanes (in order) followed by accepted overlay
+ *          lanes (in registry iteration order). Callers must not mutate it.
+ */
+function mergeReviewerLanes(firstParty, registry) {
+    // First-party always wins and is returned by reference (identity-stable), so a
+    // collision cannot perturb the first-party entry a consumer already holds.
+    const bySlug = new Map();
+    const ordered = [];
+    for (const lane of firstParty) {
+        const slug = typeof lane.slug === 'string' ? lane.slug.trim() : '';
+        if (!slug)
+            continue; // unreachable for the shipped frozen set, but this is exported
+        if (!bySlug.has(slug)) {
+            bySlug.set(slug, lane);
+            ordered.push(lane);
+        }
+    }
+    const capabilities = (registry && registry.capabilities) || {};
+    for (const cap of Object.values(capabilities)) {
+        if (cap === null || typeof cap !== 'object' || Array.isArray(cap))
+            continue;
+        const body = cap.reviewer;
+        // C1/C2 (mirroring collectReviewerLaneSurfaces): a missing, null, or
+        // non-object reviewer body declares no lane — never an error at this layer.
+        if (body === null || typeof body !== 'object' || Array.isArray(body))
+            continue;
+        const rawSlug = body.slug;
+        const slug = typeof rawSlug === 'string' ? rawSlug.trim() : '';
+        // Empty/whitespace slug: nothing to key on. Grammar-invalid slug: the
+        // path-traversal class — skip rather than admit, even though resolveLanePlan
+        // would reject it downstream. Both are skips, not throws.
+        if (!slug || !exports.LANE_SLUG_RE.test(slug))
+            continue;
+        if (bySlug.has(slug))
+            continue; // D8: first-party (or an earlier overlay) wins
+        // The body is already ReviewerLane-shaped per ADR-2782 D1. We do NOT
+        // deep-validate every field here: the invocation trust boundary
+        // (resolveLanePlan) is the seam that re-validates a lane before it runs, and
+        // `sections`/`flags` are both tolerant of a partial body (flags filters by
+        // shape; sections reads slug/reviewsSection which a non-string cap simply
+        // renders as undefined). Admitting the body keeps the merge a pure merge.
+        //
+        // The slug is normalized to its trimmed value on the stored lane so the merge
+        // and the selection roster (`deriveReviewerSlugs`, which trims before adding)
+        // agree on the canonical key — otherwise a body declaring `slug: '  x  '`
+        // would key the map on `'x'` but emit the raw `'  x  '` in `sections` and fail
+        // to match a `--selected` value coming from the roster. (The capability
+        // validator's grammar check rejects surrounding whitespace before this is
+        // reachable through a real install, so this is belt-and-braces parity with the
+        // roster, not a live-input guard.)
+        const lane = { ...body, slug };
+        bySlug.set(slug, lane);
+        ordered.push(lane);
+    }
+    return ordered;
+}
 /* ------------------------------------------------------------------ *
  * DEFECT.GENERATIVE-FIX parity (CONTEXT.md:797)
  * ------------------------------------------------------------------ */

package/gsd-core/bin/lib/review-lane-runner.cjs

@@ -283,18 +283,32 @@ function antigravityWatermark(workspace, deps) {
         return { convId, lines: deps.readFile(tx).split(/\r?\n/).filter((l) => l.trim()).length };
     }
     catch {
-        return { convId, lines: 0 };
+        // #3118: this conv-id pre-dates this run, so its transcript exists but this run cannot verify
+        // its line count. Reporting `lines: 0` would assert a fact we could not check — flag it instead
+        // so the fallback can decline rather than silently skip zero and replay a stale response.
+        return { convId, lines: 0, unreadable: true };
     }
 }
-/** Workspace lookup is case-insensitive — the leg's jq did `ascii_downcase` on both sides. */
+/**
+ * Workspace lookup is case-insensitive — the leg's jq did `ascii_downcase` on both sides.
+ *
+ * #3118: a successful `JSON.parse` does not by itself make the payload a usable object —
+ * `JSON.parse('null')` succeeds and returns `null`, so a truncated/zeroed cache file slips past
+ * the callers' parse-only try/catch. `typeof null === 'object'`, so the guard below must exclude
+ * `null` explicitly. Arrays are excluded too (not a workspace map), which also falls out of the
+ * `Object.entries`/`hasOwnProperty` lookups below returning nothing for array input.
+ */
 function resolveConvId(cache, workspace) {
-    if (Object.prototype.hasOwnProperty.call(cache, workspace)) {
-        const direct = cache[workspace];
+    if (cache === null || typeof cache !== 'object')
+        return '';
+    const record = cache;
+    if (Object.prototype.hasOwnProperty.call(record, workspace)) {
+        const direct = record[workspace];
         if (typeof direct === 'string' && direct)
             return direct;
     }
     const target = workspace.toLowerCase();
-    for (const [k, v] of Object.entries(cache)) {
+    for (const [k, v] of Object.entries(record)) {
         if (k.toLowerCase() === target && typeof v === 'string' && v)
             return v;
     }
@@ -324,6 +338,10 @@ function antigravityTranscriptFallback(workspace, mark, deps) {
     const convId = resolveConvId(cache, workspace);
     if (!convId)
         return '';
+    // #3118: the watermark could not read this conversation's transcript, so there is no trustworthy
+    // skip for it. Declining is the fail-closed answer; skipping 0 would replay a prior run's review.
+    if (mark.unreadable === true && convId === mark.convId)
+        return '';
     const tx = transcriptPath(deps.homeDir, convId);
     if (!deps.exists(tx))
         return '';
@@ -549,7 +567,13 @@ function runSpawnLane(plan, deps, repoRoot) {
         ? antigravityArgv(plan.argv, plan.promptPath, repoRoot, deps)
         : plan.argv;
     const out = deps.spawn(plan.binary, argv, { input, timeoutMs: plan.timeoutMs });
-    deps.writeFile(plan.errPath, out.stderr ?? '');
+    // #3086: surface spawn errors (ENOENT, ETIMEDOUT, etc.) that would otherwise
+    // be silently dropped — the review path read only stdout/stderr and treated
+    // an empty-stderr spawn failure as "the model had nothing to say".
+    const errContent = out.errorCode
+        ? `${out.stderr ?? ''}\n[spawn error: ${out.errorCode}]\n`
+        : (out.stderr ?? '');
+    deps.writeFile(plan.errPath, errContent);
     // `file-arg` lanes write the review themselves and their stdout is deliberately discarded (#1698).
     let review = plan.outputTarget.kind === 'file'
         ? deps.exists(plan.outputTarget.path)