@opengsd/gsd-core 1.5.0 → 1.6.0-rc.2

package/gsd-core/bin/lib/capability-loader.cjs

@@ -0,0 +1,764 @@
+"use strict";
+/**
+ * capability-loader.cts — runtime Capability Registry overlay (ADR-1244 D2).
+ *
+ * Promotes the registry from a frozen data file to a module with an interface:
+ *
+ *     loadRegistry({ includeInstalled }) -> composed registry
+ *
+ * It composes the **first-party frozen registry** (the committed, generated
+ * `capability-registry.cjs`) with a **validated installed overlay** — third-party
+ * capability manifests read at runtime from per-scope install roots:
+ *   - global:  $GSD_HOME/.gsd/capabilities/<id>/capability.json  (GSD_HOME defaults to ~)
+ *   - project: <projectRoot>/.gsd/capabilities/<id>/capability.json
+ *
+ * Invariants enforced over the merged set (first-party ∪ overlay):
+ *   - First-party always wins: an overlay whose `id`, owned skill/agent stem, or
+ *     federated config key collides with first-party (or uses a reserved `gsd-` /
+ *     `gsd-core-` / `anthropic-` id prefix) is rejected.
+ *   - Load-time re-gate (default-resilient): an overlay that fails validation or
+ *     whose `engines.gsd` does not satisfy the running GSD version is SKIPPED
+ *     with a warning — it never crashes the loop. EXCEPTION (per-hook-kind
+ *     policy): a skipped capability that declares a `gate` is recorded in
+ *     `_overlay.incompatibleGateCapIds` so the loop resolver can fail CLOSED for
+ *     that gate rather than silently proceeding as if it had passed.
+ *
+ * The merged registry is materialized by the canonical `buildRegistry`
+ * (re-exported from the generator, which ships) over a cap-map reconstructed
+ * from the frozen registry's capability objects plus the accepted overlay
+ * capabilities — so every derived view (bySkill, byLoopPoint, configSchema,
+ * capabilityClusters, profileMembership, …) is computed by exactly one builder
+ * and cannot drift from the first-party path.
+ *
+ * Install never executes capability code here (staging/exec belongs to ADR-1244
+ * D3/D5); this module only READS and VALIDATES declarations.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRegistry = loadRegistry;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const RESERVED_ID_PREFIX = /^(gsd-|gsd-core-|anthropic-)/;
+const GSD_HOME_DIRNAME = '.gsd';
+/**
+ * GENEROUS DoS backstop for the bounded per-scope ledger read (mirrors capability-ledger's
+ * LEDGER_MAX_BYTES). The project-scope ledger is repo-plantable untrusted content; reading it via
+ * the shared fd reader (regular-file + size cap) means a FIFO/device/symlinked ledger can no longer
+ * BLOCK (the #1459 raw-readFileSync hang) or read unbounded.
+ */
+const LEDGER_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * #1459 finding 2 (HIGH): GENEROUS DoS backstop on a project-plantable `capability.json`. The loader
+ * MUST read the manifest via the shared bounded fd reader (regular-file + size cap, no FIFO hang),
+ * NOT a raw `fs.readFileSync` — a repo-planted FIFO/device manifest would otherwise BLOCK the loader
+ * forever and an oversized manifest would read unbounded into memory (OOM). A legitimate manifest is a
+ * few KiB of declarative JSON; 8 MiB is wildly more than any real capability.json. A null/oversized/
+ * non-regular read → SKIP the overlay (warning), fail-closed.
+ */
+const MANIFEST_MAX_BYTES = 8 * 1024 * 1024;
+function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+// ---------------------------------------------------------------------------
+// Test seams (#1461). The validator and generator are normally `require()`d
+// fresh inside loadRegistry. These optional overrides let a test inject a
+// validator whose cross-capability check THROWS (OVL-1) or a generator whose
+// buildRegistry THROWS (OVL-2), to prove the loader still NEVER crashes the
+// loop — it skips the offending overlay with a warning / falls back to the
+// frozen first-party registry. Pass null to restore the real module.
+// ---------------------------------------------------------------------------
+let _validatorOverride = null;
+let _generatorOverride = null;
+/** Test seam: override the capability validator module. Pass null to restore. */
+function _setValidatorForTest(v) {
+    _validatorOverride = v;
+}
+/** Test seam: override the registry generator module. Pass null to restore. */
+function _setGeneratorForTest(g) {
+    _generatorOverride = g;
+}
+/** Resolve the running GSD version; fail-closed to '0.0.0' if it cannot be read. */
+function readHostVersion() {
+    try {
+        // gsd-core/bin/lib/ -> repo/package root is three levels up.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const pkg = require('../../../package.json');
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Canonicalize a directory path for dedup/scope-escalation comparison. #1459 finding 1 (HIGH): the dedup
+ * MUST collapse two DIFFERENT LEXICAL paths that name the SAME PHYSICAL directory (a symlink) to one key,
+ * else a symlinked GSD_HOME aliasing the project root is scanned once as trusted 'global' BEFORE the
+ * 'project' scan and the in-repo `.gsd/capabilities` bundle bypasses the CB-3 consent gate via aliasing.
+ * `fs.realpathSync` resolves symlinks to the physical path; on ENOENT/IO error it falls back to
+ * `path.resolve` (a not-yet-created overlay dir cannot be realpath'd).
+ *
+ * #1459 CONVERGENCE finding 3 (LOW/MED): the realpath FAILURE must be reported to the caller (the
+ * `realpathFailed` flag), NOT silently swallowed. The old behavior — fall back to `path.resolve` while
+ * preserving the candidate's ORIGINAL scope — was not strictly fail-safe: a symlinked GSD_HOME whose
+ * realpath THROWS (a race / odd-FS) would key on its SYMLINK-LEXICAL path, which differs from the
+ * project candidate's realpath'd key, so the two would NOT merge and the aliased global root would be
+ * scanned as trusted-'global' (no consent record required) — parking an aliased project tree in the
+ * trusted-global slot. The caller (`overlayRoots`) uses `realpathFailed` to classify a realpath-failed
+ * GLOBAL candidate CONSERVATIVELY (consent-required 'project'), so a race/odd-FS can never aliased-upgrade
+ * an in-repo bundle to trusted-global. The fallback key is still `path.resolve` (best-effort dedup); a
+ * normal ENOENT (the global capabilities dir simply does not exist yet) still resolves to no scan because
+ * the later readdir fails — the conservative reclassification is harmless when there is nothing to read.
+ */
+function canonicalDir(dir) {
+    try {
+        return { path: fs.realpathSync(dir), realpathFailed: false, enoent: false };
+    }
+    catch (err) {
+        // #1459 finding 1 (round 6): distinguish a NON-EXISTENT overlay dir (ENOENT — there is simply nothing
+        // to scan at that scope, so the fail-safe demotion must NOT fire) from a realpath that fails for ANOTHER
+        // reason (race / odd-FS / EIO / EACCES — the dir may exist but is uncanonicalizable, so we cannot prove
+        // physical distinctness and MUST fail safe toward needs-consent).
+        const code = err.code;
+        const enoent = code === 'ENOENT' || code === 'ENOTDIR';
+        return { path: path.resolve(dir), realpathFailed: true, enoent };
+    }
+}
+/**
+ * The ordered overlay install roots (global first, then project), deduped by
+ * CANONICAL (realpath'd) absolute path so a single physical directory is never scanned twice (which
+ * would otherwise self-report a spurious id collision when the project lives
+ * under the GSD home, or in tests where both resolve to the same fixture).
+ *
+ * #1459 CB-3: when the consent-global home resolves EQUAL to (or an ancestor whose .gsd collides with)
+ * a GENUINE project root, the global overlay dir and the project overlay dir are the SAME directory.
+ * The dedup must NOT then keep it as 'global' (trusted, no consent record required) — that would let an
+ * in-repo bundle bypass consent simply because GSD_HOME pointed at the repo. On a collision the
+ * surviving scope escalates to the MORE RESTRICTIVE 'project' (consent-required), but ONLY when the
+ * colliding root is a GENUINE marker'd project (a `.planning/` dir or a `.git`). `findProjectRoot` is
+ * total — it returns `cwd` itself when no marker exists — so a bare GSD_HOME with no project marker
+ * (the user's own home; also the test-fixture `cwd === home` no-op) must stay 'global' and NOT spuriously
+ * demand consent.
+ *
+ * #1459 finding 1 (HIGH): BOTH the dedup key AND the CB-3 collision comparison are keyed on the
+ * realpath'd path (canonicalDir), so a symlinked GSD_HOME that physically IS the project root collides
+ * and escalates to consent-required 'project' — it can no longer be aliased into the trusted-global slot.
+ *
+ * #1459 finding 1 (HIGH, ROUND 6): the trusted-global slot is now gated on PROVABLE distinctness from the
+ * project tree — realpath(global) AND realpath(project) must BOTH succeed AND resolve to DIFFERENT physical
+ * paths. The earlier one-sided rule (demote only a realpath-FAILED *global* candidate) still allowed the
+ * symlinked-GSD_HOME bypass: when GSD_HOME aliases the project root, the GLOBAL candidate realpaths fine
+ * while the PROJECT candidate's realpath fails, so the keys never collide and the in-repo bundle stays in
+ * the no-consent global slot. If distinctness cannot be proven (either realpath throws, or both resolve
+ * EQUAL) AND there is a genuine project root, the global is demoted to consent-required 'project'.
+ */
+function hasGenuineProjectMarker(dir) {
+    try {
+        const planning = path.join(dir, '.planning');
+        if (fs.existsSync(planning) && fs.statSync(planning).isDirectory())
+            return true;
+    }
+    catch { /* fall through */ }
+    try {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return true;
+    }
+    catch { /* fall through */ }
+    return false;
+}
+function overlayRoots(cwd, gsdHome) {
+    const roots = [];
+    const byPath = new Map();
+    const add = (dir, scope, canonical, genuineProject = false) => {
+        const resolved = path.resolve(dir);
+        // #1459 finding 1: the DEDUP KEY (and thus the CB-3 scope-escalation comparison) is the CANONICAL
+        // (realpath'd) path, so a symlinked GSD_HOME that physically IS the project root collides here (and
+        // escalates below) instead of being scanned as a distinct trusted 'global' root. The SCANNED path
+        // (`entry.dir`) stays the lexical `path.resolve` value — the readdir/commandRoots path is unchanged
+        // for the common (non-symlinked) case; only the dedup/escalation decision is realpath-aware.
+        const key = canonical.path;
+        const existing = byPath.get(key);
+        if (existing) {
+            // CB-3: a dir already claimed escalates to the more restrictive scope ONLY for a GENUINE project
+            // root — so a real GSD_HOME == projectRoot (incl. via a symlink) still requires consent, while a
+            // marker-less home stays trusted-global (and the test-fixture cwd===home no-op is preserved).
+            if (existing.scope === 'global' && scope === 'project' && genuineProject)
+                existing.scope = 'project';
+            return;
+        }
+        const entry = { dir: resolved, scope };
+        byPath.set(key, entry);
+        roots.push(entry);
+    };
+    const home = gsdHome || process.env['GSD_HOME'] || os.homedir();
+    const globalDir = path.join(home, GSD_HOME_DIRNAME, 'capabilities');
+    const globalCanon = canonicalDir(globalDir);
+    let projectRoot = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const projectRootMod = require('./project-root.cjs');
+        projectRoot = projectRootMod.findProjectRoot(cwd);
+    }
+    catch {
+        projectRoot = null;
+    }
+    const projectDir = projectRoot ? path.join(projectRoot, GSD_HOME_DIRNAME, 'capabilities') : null;
+    const projectCanon = projectDir ? canonicalDir(projectDir) : null;
+    // #1459 finding 1 (HIGH, round 6): the global overlay root is trusted (consent-FREE) ONLY when we can
+    // PROVE it is a distinct physical directory from the project overlay tree — i.e. realpath(global) AND
+    // realpath(project) BOTH succeed AND resolve to DIFFERENT physical paths. A one-sided rule (demote only a
+    // realpath-FAILED *global* candidate) left the symlinked-GSD_HOME bypass open: when GSD_HOME is a symlink
+    // alias of the project root, the GLOBAL candidate realpaths fine (stays trusted-global) while the PROJECT
+    // candidate's realpath fails → the two keys never collide → the in-repo bundle stays in the no-consent
+    // global slot. So the global is demoted to consent-required 'project' (only when there IS a GENUINE
+    // project root, so a marker-less home / cwd===home stays trusted-global) whenever distinctness cannot be
+    // proven: EITHER realpath throws, OR both succeed but resolve EQUAL (an alias). When the demoted-global
+    // and the project candidate physically coincide they then dedup onto one consent-required entry; when
+    // they are merely unprovable-distinct (e.g. global realpath failed) the global is independently demoted
+    // so an aliased in-repo tree it would scan still requires a record. A genuinely non-existent global dir
+    // (ENOENT) realpath-fails too, but its later readdir fails, so this demotion is a harmless no-op there.
+    let globalScope = 'global';
+    if (projectRoot && projectCanon && hasGenuineProjectMarker(projectRoot)) {
+        // The fail-safe only matters when there IS an in-repo overlay tree to protect. A NON-EXISTENT project
+        // overlay dir (ENOENT) has nothing to bypass into the trusted-global slot, so the global stays trusted
+        // (and a genuinely distinct real global cap is not spuriously demoted — the control case). Otherwise,
+        // demote the global to consent-required 'project' UNLESS we can PROVE physical distinctness:
+        //   - the project overlay actually exists (or can't be proven absent), AND
+        //   - either realpath can't canonicalize one side (race/odd-FS → can't prove distinct), OR
+        //   - both canonicalize EQUAL (an alias — GSD_HOME physically IS the project root).
+        const projectAbsent = projectCanon.realpathFailed && projectCanon.enoent;
+        if (!projectAbsent) {
+            const provablyDistinct = !globalCanon.realpathFailed &&
+                !projectCanon.realpathFailed &&
+                globalCanon.path !== projectCanon.path;
+            if (!provablyDistinct)
+                globalScope = 'project';
+        }
+    }
+    add(globalDir, globalScope, globalCanon);
+    if (projectDir && projectCanon) {
+        add(projectDir, 'project', projectCanon, hasGenuineProjectMarker(projectRoot));
+    }
+    return roots;
+}
+/**
+ * Resolve the PROJECT ROOT for `cwd` used to LOOK UP a project-scope consent record (#1459). Delegates
+ * to the SINGLE canonical `consentProjectRoot` helper (IC-01/CB-4) so the loader's lookup key always
+ * matches the install RECORD key and the `trust revoke` key — installing from a subdir then resolves
+ * to the same realpath'd project root the loader checks (no install-then-inactive). Falls back to
+ * `cwd` if the project-root module cannot be loaded at all (the consent store realpaths it).
+ */
+function projectRootFor(cwd) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const projectRootMod = require('./project-root.cjs');
+        return projectRootMod.consentProjectRoot(cwd);
+    }
+    catch { /* fall through */ }
+    return cwd;
+}
+/**
+ * Read the per-scope ledger co-located with an overlay root (the root is `<scope>/.gsd/capabilities`,
+ * so its ledger is `<scope>/.gsd-capabilities.json`) and classify its ids:
+ *   - `pending`:   ids carrying an in-flight `_pending` intent (crashed/uncommitted install/upgrade)
+ *                  — must not be activated until reconciliation completes.
+ *   - `committed`: ids with a ledger entry and NO `_pending` — i.e. an install the user actually
+ *                  completed (and, for executable surfaces, CONSENTED to). This is the authoritative
+ *                  consent signal required before dispatching a capability's CLI COMMANDS (ADR-1244
+ *                  Phase 5 / D7): a bundle merely dropped on disk with no ledger entry is NOT
+ *                  consented and its command family must not be dispatchable.
+ * Never throws: a missing/invalid ledger yields empty sets.
+ */
+/**
+ * Is `e` a structurally-valid COMMITTED ledger entry for `id`? Delegates the structural shape to
+ * capability-ledger's SHARED `isValidLedgerEntry` (loader/ledger validator PARITY — #1459 ROOT FIX:
+ * the loader previously hand-duplicated the shape and could drift), and ADDS the loader-specific
+ * "committed = valid AND carries NO `_pending` marker" semantic. A malformed/tampered/pending entry
+ * fails this check and is therefore NOT treated as committed — fail closed.
+ */
+function isCommittedLedgerEntry(ledger, id, e) {
+    if (!e || typeof e !== 'object' || Array.isArray(e))
+        return false;
+    if (Object.prototype.hasOwnProperty.call(e, '_pending'))
+        return false; // intent ⇒ uncommitted.
+    return ledger.isValidLedgerEntry(id, e);
+}
+function ledgerOverlayIds(ledger, rootDir) {
+    const pending = new Set();
+    const committed = new Set();
+    try {
+        const ledgerPath = path.join(rootDir, '..', '..', '.gsd-capabilities.json');
+        // #1459 (HIGH): read the per-scope ledger via the SHARED fd-based bounded reader (open → fstat →
+        // require regular file → size cap → read exactly size). The previous raw `fs.readFileSync` BLOCKED
+        // forever on a repo-planted FIFO ledger (a project-scope DoS) and read an oversized file whole.
+        const content = ledger.readSmallRegularFile(ledgerPath, LEDGER_MAX_BYTES);
+        if (content === null)
+            return { pending, committed }; // genuinely missing.
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== 'object')
+            return { pending, committed };
+        const entries = parsed['entries'];
+        if (!entries || typeof entries !== 'object' || Array.isArray(entries))
+            return { pending, committed };
+        for (const [id, entry] of Object.entries(entries)) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            if (entry['_pending']) {
+                pending.add(id); // a truthy in-flight intent — defer/skip until reconciliation
+            }
+            else if (isCommittedLedgerEntry(ledger, id, entry)) {
+                committed.add(id); // a genuine, structurally-valid commit
+            }
+            // else: malformed / tampered / falsy-_pending → neither (fail closed: declarative-only)
+        }
+    }
+    catch { /* missing/invalid/non-regular/oversized ledger — no pending, no committed (fail closed) */ }
+    return { pending, committed };
+}
+/** Shallow-attach overlay diagnostics WITHOUT mutating the frozen registry module. */
+function withOverlayMeta(reg, meta) {
+    return Object.assign({}, reg, { _overlay: meta });
+}
+/**
+ * Loop extension points a capability declares a gate at (the `point` strings off `cap.gates`).
+ * SINGLE source of truth shared by BOTH the per-candidate `skip()` closure AND the OVL-2
+ * buildRegistry-failure fallback (#1461) so a dropped gate-declaring overlay fails CLOSED via the
+ * SAME extraction the per-candidate path uses — never one path blocking and the other failing open.
+ *
+ * #1461 finding 1 (HIGH): this MUST be TOTAL over an UNTRUSTED, possibly-malformed manifest — it
+ * runs on a candidate BEFORE per-candidate validation has confirmed the shape. A null `cap`, a
+ * non-object `cap`, a non-array `cap.gates` (e.g. `gates: {}` / `gates: null`), or a malformed gate
+ * ENTRY (`gates: [null]` / `gates: ["x"]` / a gate with a non-string `point`) must NEVER throw: it
+ * returns only the extractable `point` strings, filtering null/non-object/malformed entries. A
+ * `null` gate has no extractable point, so it contributes nothing (no spurious fail-closed block).
+ */
+function gatePointsOf(cap) {
+    if (!cap || typeof cap !== 'object')
+        return [];
+    const gates = cap.gates;
+    if (!Array.isArray(gates))
+        return [];
+    return gates
+        .map((g) => g && typeof g === 'object' && typeof g.point === 'string'
+        ? g.point
+        : null)
+        .filter((p) => typeof p === 'string');
+}
+/**
+ * Load the capability registry, optionally composing the installed overlay.
+ *
+ * @returns the registry object (same shape as `capability-registry.cjs`). When
+ *   overlays are considered, an `_overlay` field carries skip warnings and the
+ *   fail-closed gate list. With `includeInstalled` falsy, the frozen first-party
+ *   registry is returned unchanged (identity-stable).
+ */
+function loadRegistry(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const base = require('./capability-registry.cjs');
+    if (!options.includeInstalled)
+        return base;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const validator = _validatorOverride ?? require('./capability-validator.cjs');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const semver = require('./semver-compare.cjs');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const ledgerMod = require('./capability-ledger.cjs');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const consentMod = require('./capability-consent.cjs');
+    const cwd = options.cwd || process.cwd();
+    const hostVersion = options.hostVersion || readHostVersion();
+    // The user-owned consent home — SAME `gsdHome || GSD_HOME || homedir()` rule the CLI uses, so the
+    // consent the CLI records is the consent the loader checks. The consent store NEVER lives in a repo.
+    const gsdHome = options.gsdHome || process.env['GSD_HOME'] || os.homedir();
+    const warnings = [];
+    const incompatibleGateCapIds = [];
+    const blockedGates = [];
+    const commandRoots = {};
+    const overlayCaps = [];
+    // First-party reservations — first-party always wins.
+    const fpCaps = (base.capabilities ?? {});
+    const fpBySkill = (base.bySkill ?? {});
+    const fpByAgent = (base.byAgent ?? {});
+    const fpConfigKeys = (base.configKeys ?? {});
+    const fpConfigSchema = (base.configSchema ?? {});
+    const fpFamilies = (base.commandFamilies ?? {});
+    const fpIds = new Set(Object.keys(fpCaps));
+    const claimedSkills = new Set(Object.keys(fpBySkill));
+    const claimedAgents = new Set(Object.keys(fpByAgent));
+    const claimedConfig = new Set([...Object.keys(fpConfigKeys), ...Object.keys(fpConfigSchema)]);
+    const claimedFamilies = new Set(Object.keys(fpFamilies));
+    const acceptedIds = new Set();
+    // Running merged cap-map (first-party ∪ accepted overlays). A candidate is
+    // accepted only if the FULL cross-capability suite stays clean after adding it
+    // (first-party alone is clean, so any new error is the candidate's fault) — the
+    // overlay can never violate the same invariants the build-time generator enforces.
+    const acceptedMap = new Map(Object.entries(fpCaps));
+    // Generator (buildRegistry + central config keys) loaded lazily — only when at
+    // least one overlay candidate exists, so the no-overlay fast path stays cheap.
+    let generatorMod = null;
+    const getGenerator = () => {
+        if (generatorMod)
+            return generatorMod;
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const mod = _generatorOverride ?? require('../../../scripts/gen-capability-registry.cjs');
+        generatorMod = mod;
+        return mod;
+    };
+    let centralKeys = null;
+    const getCentralKeys = () => {
+        if (!centralKeys) {
+            try {
+                centralKeys = getGenerator().loadCentralConfigKeys();
+            }
+            catch {
+                centralKeys = new Set();
+            }
+        }
+        return centralKeys;
+    };
+    for (const root of overlayRoots(cwd, options.gsdHome)) {
+        let entries;
+        try {
+            entries = fs.readdirSync(root.dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // no overlay dir at this scope — normal
+        }
+        // Ids whose ledger entry carries an in-flight `_pending` intent (a crashed/uncommitted
+        // install or upgrade). They are NOT yet committed, so they must not be activated — reconcile
+        // will roll them forward or back. Fail OPEN (skip without a gate block): an uncommitted gate
+        // is not a real installed gate. See capability-lifecycle.cts (ADR-1244 Phase 4).
+        const { pending: pendingIds, committed: committedIds } = ledgerOverlayIds(ledgerMod, root.dir);
+        for (const ent of entries) {
+            if (!ent.isDirectory())
+                continue;
+            const id = ent.name;
+            const capDir = path.join(root.dir, id);
+            const manifestPath = path.join(capDir, 'capability.json');
+            if (pendingIds.has(id)) {
+                warnings.push({ id, scope: root.scope, reason: 'install/upgrade in progress (uncommitted) — deferred until reconciliation' });
+                continue;
+            }
+            let cap;
+            try {
+                // #1459 finding 2 (HIGH): read the manifest via the SHARED fd-based bounded reader (open → fstat
+                // → require regular file → size cap → read exactly size). A project-planted FIFO/device manifest
+                // can no longer BLOCK the loader (the raw readFileSync hang) and an oversized manifest can no
+                // longer read unbounded. A null read (genuinely missing OR refused as non-regular/oversized) →
+                // skip the overlay, fail-closed.
+                const manifestRaw = ledgerMod.readSmallRegularFile(manifestPath, MANIFEST_MAX_BYTES);
+                if (manifestRaw === null) {
+                    warnings.push({ id, scope: root.scope, reason: 'capability.json missing, non-regular (FIFO/device), or exceeds the size cap — skipped' });
+                    continue;
+                }
+                cap = JSON.parse(manifestRaw);
+            }
+            catch (e) {
+                warnings.push({ id, scope: root.scope, reason: 'unreadable or invalid capability.json: ' + errMessage(e) });
+                continue;
+            }
+            // Points at which this capability declares a gate — used to fail CLOSED if
+            // the capability is skipped (a skipped deploy gate must block, not pass).
+            const gatePoints = gatePointsOf(cap);
+            const declaresGate = gatePoints.length > 0;
+            const skip = (reason) => {
+                warnings.push({ id, scope: root.scope, reason });
+                if (declaresGate) {
+                    incompatibleGateCapIds.push(id);
+                    for (const point of gatePoints)
+                        blockedGates.push({ point, capId: id, reason });
+                }
+            };
+            // #1461 finding 1 (HIGH): make the ENTIRE per-candidate processing body TOTAL. The committed
+            // validator is NOT total for malformed ARRAY entries — validateGate/validateStep/
+            // validateContribution dereference an entry (`.point`, `.into`, …) BEFORE any shape check, so a
+            // manifest with `gates: [null]` (or `steps: [null]` / `contributions: [null]`) makes
+            // validateCapability THROW `Cannot read properties of null (reading 'point')`. That throw was
+            // OUTSIDE any per-candidate guard → it escaped loadRegistry and crashed EVERY consumer
+            // (loop-resolver, config-loader, surface, capability-state, gsd-tools). ADR-1244 D2 mandates a
+            // malformed overlay is SKIPPED with a warning, never crashes the loop. Wrapping the whole body
+            // (manifest already parsed above) means ANY throw from ANY validator/step becomes a structured
+            // `skip()` + continue to the next candidate — which ALSO fail-closes a declared gate (the `skip`
+            // closure records incompatibleGateCapIds/blockedGates for the extractable gate points). The
+            // existing structured skip/continue paths inside are unchanged; this is a fail-safe BACKSTOP for
+            // a validator/step that THROWS rather than returning errors. `continue` inside this try simply
+            // advances the `for` loop (there is no finally to interfere).
+            try {
+                // 1. Reserved namespace — third-party may not impersonate first-party.
+                if (RESERVED_ID_PREFIX.test(id)) {
+                    skip('id uses a reserved first-party prefix (gsd-/gsd-core-/anthropic-)');
+                    continue;
+                }
+                // 2. Per-capability structural + version-envelope validation.
+                const errs = validator.validateCapability(cap, id);
+                if (errs.length) {
+                    skip('failed validation: ' + errs.join('; '));
+                    continue;
+                }
+                // 3. First-party wins + overlay/overlay de-dup on id, skill, agent, config key.
+                if (fpIds.has(id) || acceptedIds.has(id)) {
+                    skip('id collides with an already-registered capability');
+                    continue;
+                }
+                const skills = Array.isArray(cap.skills) ? cap.skills : [];
+                const agents = Array.isArray(cap.agents) ? cap.agents : [];
+                const cfgKeys = cap.config && typeof cap.config === 'object' && !Array.isArray(cap.config)
+                    ? Object.keys(cap.config) : [];
+                const skillClash = skills.find((s) => claimedSkills.has(s));
+                if (skillClash) {
+                    skip('owns skill "' + skillClash + '" already owned by another capability');
+                    continue;
+                }
+                const agentClash = agents.find((a) => claimedAgents.has(a));
+                if (agentClash) {
+                    skip('owns agent "' + agentClash + '" already owned by another capability');
+                    continue;
+                }
+                const cfgClash = cfgKeys.find((k) => claimedConfig.has(k));
+                if (cfgClash) {
+                    skip('owns config key "' + cfgClash + '" already owned by another capability');
+                    continue;
+                }
+                const families = Array.isArray(cap.commands)
+                    ? cap.commands
+                        .map((c) => (c && typeof c === 'object' && typeof c.family === 'string' ? c.family : null))
+                        .filter((f) => typeof f === 'string')
+                    : [];
+                const familyClash = families.find((f) => claimedFamilies.has(f));
+                if (familyClash) {
+                    skip('owns command family "' + familyClash + '" already owned by another capability');
+                    continue;
+                }
+                // 4. Load-time engines.gsd re-gate.
+                const range = cap.engines?.gsd;
+                if (typeof range === 'string' && range && !semver.semverSatisfies(hostVersion, range)) {
+                    skip('incompatible with GSD ' + hostVersion + ' (requires engines.gsd "' + range + '")');
+                    continue;
+                }
+                // 5. #1459 — USER-OWNED CONSENT GATE (TRUST-1 + TRUST-3). For a PROJECT-scope overlay the
+                //    authoritative consent signal is NOT the in-repo ledger (repo-plantable: a clone/fork
+                //    activated executable surfaces AND declarative loop surfaces with no user decision) but a
+                //    record in the user-owned consent store on THIS machine, bound to (realpath(projectRoot),
+                //    id, RECOMPUTED full-bundle content hash). If there is NO matching record we do NOT push
+                //    the cap into acceptedMap/overlayCaps and do NOT set a commandRoot → the cap is
+                //    DISCOVERED-BUT-INACTIVE (a warning records why). This single gate closes BOTH
+                //    command-dispatch (TRUST-1) and declarative-surface (TRUST-3) activation. GLOBAL scope is
+                //    under the user's own home and is trusted as before (no consent record required).
+                //
+                //    CONVERGENCE finding 1 (HIGH): this gate now runs BEFORE the heavy/unbounded pre-activation
+                //    work (materializeHookFragments — which reads each `fragment.path` off disk — and the full
+                //    cross-capability validation). A forged in-repo PROJECT overlay can point a `fragment.path`
+                //    at an in-bundle FIFO/oversized file; materializing it BEFORE the consent check would
+                //    hang/OOM the loader before the unconsented → inactive fail-closed path is reached. Running
+                //    the (already bounded + fail-closed) consent recompute FIRST means an unconsented project
+                //    overlay skips with NO further disk work. The gate's DECISION is identical — only the
+                //    work-ordering moved (consented project overlays + GLOBAL overlays still materialize below).
+                //
+                //    CONTENT BINDING (#1459 round 2, CB-1/CB-2/TRUST2-5): the binding is the bundle CONTENT
+                //    HASH recomputed HERE over the on-disk capDir (manifest AND artifacts AND identity) — NOT
+                //    the ledger `integrity` (which is `''` for path/git/dir installs and taken verbatim from
+                //    the repo-plantable project ledger → degenerate `'' === ''`) and NOT the executable-only
+                //    disclosure signature (a declarative-only swap leaves it constant). Any tamper — a swapped
+                //    declarative capability.json, an edited hook script, an empty-integrity local install —
+                //    changes the recomputed hash and the cap stays inactive. `bundleContentHash` is itself
+                //    bounded + fail-closed (it refuses non-regular bundle files and reads via the shared bounded
+                //    reader), so it cannot hang on a forged FIFO bundle file. The whole lookup is wrapped so a
+                //    consent-store read / hash-recompute failure fails CLOSED (inactive), never crashing the
+                //    loop (the loader must stay non-throwing end to end).
+                //
+                //    IRREDUCIBLE TOCTOU LIMIT (#1459 / mirrors the #1462 lock-release residual): the hash
+                //    verified HERE binds the bundle's on-disk content at THIS instant. A local writer racing
+                //    between this verification and the capability's LATER execution (a hook firing, a command
+                //    dispatch) can still mutate the bundle files after the check passes — this is a filesystem
+                //    primitive limit, not a loader bug: short of fd-pinned execution or an atomic content
+                //    snapshot (which needs native support we do not have here), no userspace check can close the
+                //    window between "verify content" and "execute content". This is documented, not dismissed:
+                //    the gate is the strongest defense available at this layer (any persisted tamper is caught on
+                //    the NEXT load), and the residual race requires an attacker already able to write the project
+                //    tree at execution time.
+                if (root.scope === 'project') {
+                    let consented = false;
+                    try {
+                        consented = consentMod.hasProjectConsent({
+                            gsdHome,
+                            projectRoot: projectRootFor(cwd),
+                            id,
+                            contentHash: consentMod.bundleContentHash(capDir),
+                        });
+                    }
+                    catch {
+                        consented = false; // fail closed — a consent-store/hash-recompute failure never activates a cap.
+                    }
+                    if (!consented) {
+                        // DISCOVERED-BUT-INACTIVE: no user consent record on this machine. NOT a gate block (an
+                        // unconsented project gate is not a real installed gate — same fail-open posture as
+                        // `_pending`); it simply does not contribute any surface. #1459 IC-02: tag the skip with the
+                        // structural `kind: 'unconsented'` so gsd-tools `list` marks it INACTIVE by discriminant, not
+                        // by matching the (changeable) reason prose. NOTE (convergence finding 1): we `continue` here
+                        // BEFORE materializeHookFragments, so an unconsented project overlay's fragment files are never
+                        // read — a forged FIFO/oversized fragment cannot hang/OOM the loop.
+                        warnings.push({ id, scope: root.scope, kind: 'unconsented', reason: 'discovered — no user consent record (inactive)' });
+                        continue;
+                    }
+                }
+                // 5b. Materialize path-based hook fragments (resolved against the overlay dir). Runs AFTER the
+                //    project consent gate (convergence finding 1) so only a CONSENTED project overlay (or a
+                //    trusted GLOBAL overlay) reaches the fragment reads. materializeHookFragments RETURNS errors
+                //    (e.g. a fragment path escaping the capability dir, OR — convergence finding 1(b) — a fragment
+                //    that is non-regular/oversized and refused by the shared bounded reader) — capture them; an
+                //    un-materializable fragment is a skip, never a hang.
+                let fragErrs;
+                try {
+                    fragErrs = validator.materializeHookFragments(cap, capDir) || [];
+                }
+                catch (e) {
+                    skip('hook fragment could not be materialized: ' + errMessage(e));
+                    continue;
+                }
+                if (fragErrs.length) {
+                    skip('invalid hook fragment: ' + fragErrs.join('; '));
+                    continue;
+                }
+                // 6. Full cross-capability validation over the merged set (the same invariants
+                //    the build-time generator enforces): contract roles, consumes-satisfiability,
+                //    owner-uniqueness, config-key exclusivity vs central schema, requires acyclicity
+                //    + tier-monotone. Incremental: add the candidate, validate, drop on any error.
+                acceptedMap.set(id, cap);
+                // #1461 OVL-1 (HIGH): these validators are CONTRACTED to RETURN error arrays, but one can THROW
+                // (e.g. validateConsumesGlobal asserting on a duplicate producer). An unguarded throw here
+                // escapes loadRegistry and crashes EVERY consumer (loop-resolver, config-loader, surface,
+                // capability-state, gsd-tools). ADR-1244 D2: a malformed overlay is SKIPPED with a warning,
+                // never crashes the loop. So a throwing validator is treated EXACTLY like a validation failure:
+                // drop this one candidate (with a warning) and continue — the rest of the overlay set is
+                // unaffected. (The returns-errors path below is unchanged.)
+                let crossErrs;
+                try {
+                    crossErrs = [
+                        ...validator.validateAgainstContract(cap, id),
+                        ...validator.validateConsumesGlobal(acceptedMap),
+                        ...validator.validateCrossCapability(acceptedMap, getCentralKeys()),
+                    ];
+                }
+                catch (e) {
+                    acceptedMap.delete(id);
+                    skip('cross-capability validation error: ' + errMessage(e));
+                    continue;
+                }
+                if (crossErrs.length) {
+                    acceptedMap.delete(id);
+                    skip('cross-capability validation failed: ' + crossErrs.slice(0, 3).join('; '));
+                    continue;
+                }
+                // Accepted.
+                overlayCaps.push(cap);
+                acceptedIds.add(id);
+                for (const s of skills)
+                    claimedSkills.add(s);
+                for (const a of agents)
+                    claimedAgents.add(a);
+                for (const k of cfgKeys)
+                    claimedConfig.add(k);
+                for (const f of families)
+                    claimedFamilies.add(f);
+                // Record the install root for a third-party cap that ships command modules, so a runtime
+                // dispatcher can require() the router FROM the install root (ADR-1244 Phase 5 / D7). Gated on
+                // a COMMITTED ledger entry (committedIds): executable CLI commands run only for a capability
+                // the user actually installed+consented to via the lifecycle — a bundle merely dropped on
+                // disk with no ledger entry provides declarative surfaces (Phase 2) but is NOT command-
+                // dispatchable. (Project-scope ledgers live in the repo tree and are thus only as trustworthy
+                // as the repo — see docs/explanation/capability-trust-model.md.)
+                if (families.length > 0 && committedIds.has(id))
+                    commandRoots[id] = capDir;
+            }
+            catch (e) {
+                // #1461 finding 1 (HIGH): ANY throw from ANY validator/step in the per-candidate body lands
+                // here — drop just THIS candidate with a structured skip-warning and continue with the rest of
+                // the overlay set (the loop is never crashed). `skip()` ALSO fail-closes the candidate's
+                // declared gates (incompatibleGateCapIds/blockedGates) so a malformed gate-declaring overlay
+                // blocks rather than silently passing. Remove any half-committed acceptedMap entry so the
+                // partially-processed candidate cannot leak into the final buildRegistry compose.
+                acceptedMap.delete(id);
+                skip('overlay processing error: ' + errMessage(e));
+                continue;
+            }
+        }
+    }
+    const meta = { warnings, incompatibleGateCapIds, blockedGates, commandRoots };
+    if (overlayCaps.length === 0) {
+        // Nothing to compose. Return the frozen registry unchanged when there is
+        // also nothing to report (identity-stable); otherwise attach diagnostics.
+        if (warnings.length === 0)
+            return base;
+        return withOverlayMeta(base, meta);
+    }
+    // Compose via the canonical builder so every derived view matches first-party.
+    // acceptedMap already holds first-party ∪ accepted overlays (validated above).
+    //
+    // #1461 OVL-2 (HIGH): an overlay can pass every per-candidate step yet trip a STRICTER whole-build
+    // check inside buildRegistry (config-slice shape, topo cycle across the merged set, configFormat
+    // parity). An unguarded buildRegistry throw escapes loadRegistry and crashes the loop. ADR-1244 D2
+    // mandates NEVER-CRASH: on a compose failure, fall back to the frozen FIRST-PARTY registry plus a
+    // warning recording why — the loop still gets a usable registry, just without the overlay surfaces.
+    try {
+        const merged = getGenerator().buildRegistry(acceptedMap);
+        return withOverlayMeta(merged, meta);
+    }
+    catch (e) {
+        const reason = 'buildRegistry failed composing overlays: ' + errMessage(e) + '; falling back to first-party';
+        meta.warnings.push({ id: '*', scope: 'global', reason });
+        // #1461 finding 3 (LOW): the fallback DROPS every accepted overlay, so NO dropped overlay may
+        // retain a command root. A stale `commandRoots[capId]` would let a runtime dispatcher require()/
+        // run a third-party command family FROM the install root of a capability the fallback decided NOT
+        // to load. Clear the map (the first-party base never lists overlay commandRoots — first-party
+        // command modules ship in bin/lib/, not via _overlay.commandRoots).
+        meta.commandRoots = {};
+        // #1461 OVL-2 fail-CLOSED on compose failure (HIGH): the fallback DROPS every accepted overlay,
+        // so any accepted overlay that DECLARED a gate would have its gate silently vanish → a blocking
+        // gate FAILS OPEN, violating ADR-1244 (a skipped capability declaring a gate must FAIL CLOSED).
+        // Record each dropped gate-declaring overlay's gate as blocked using the SAME extraction the
+        // per-candidate `skip()` closure uses (gatePointsOf), so loop-resolver injects the synthetic
+        // blocking gate at each declared point exactly as it would for a per-candidate skip.
+        for (const cap of overlayCaps) {
+            const gatePoints = gatePointsOf(cap);
+            if (gatePoints.length === 0)
+                continue;
+            meta.incompatibleGateCapIds.push(cap.id);
+            for (const point of gatePoints)
+                meta.blockedGates.push({ point, capId: cap.id, reason });
+        }
+        return withOverlayMeta(base, meta);
+    }
+}
+module.exports = { loadRegistry, _setValidatorForTest, _setGeneratorForTest };