@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -32,7 +32,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
-const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, } = conversionModule;
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, } = conversionModule;
 // #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
 // stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
 // `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
@@ -40,6 +40,8 @@ const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _pr
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const workflowFragmentsModule = require("./workflow-fragments.cjs");
 const { composeWorkflow: _composeWorkflow } = workflowFragmentsModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installModelOverrideResolver = require("./install-model-override-resolver.cjs");
 // ---------------------------------------------------------------------------
 // Profile definitions
 // ---------------------------------------------------------------------------
@@ -137,9 +139,79 @@ function parseCallsAgents(content) {
  * Also derives calls_agents for each skill by scanning the body text for
  * `gsd-*` agent name references. Agent stems are stored under the special
  * key `_calls_agents_<stem>` so they don't conflict with skill stems.
+ *
+ * #3798: command bodies are thin delegators — the actual `subagent_type=`
+ * spawns live in the workflow files each command references
+ * (`@…/workflows/<name>.md`). The agent derivation therefore ALSO reads every
+ * workflow file the command references (plus the workflow's steps/ fragments
+ * when it is split per the progressive-disclosure pattern) and unions their
+ * `gsd-*` tokens into the same `_calls_agents_<stem>` set. Without this,
+ * tiered profiles omitted agents their own installed skills spawn
+ * (gsd-verifier at execute-phase's verify_phase_goal was the filed repro).
+ * Over-inclusion fails safe: a tiered profile installing one extra agent
+ * costs bytes, never a broken spawn.
  */
 const DEFAULT_COMMANDS_DIR = node_path_1.default.resolve(__dirname, '..', '..', '..', 'commands', 'gsd');
-function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
+const DEFAULT_WORKFLOWS_DIR = node_path_1.default.resolve(__dirname, '..', '..', 'workflows');
+/**
+ * Collect the `gsd-*` agent tokens from every workflow file a command body
+ * references. References are the `workflows/<name>.md` path suffixes the
+ * delegating commands embed (`@…/gsd-core/workflows/<name>.md`). A
+ * split workflow (workflows/<name>/steps/*.md) contributes its fragments as
+ * well, because the parent dispatches into them and the spawns live there.
+ */
+function workflowAgentRefs(content, workflowsDir) {
+    const refs = content.match(/workflows\/([a-z0-9][a-z0-9-]*)\.md/g) || [];
+    const names = [...new Set(refs.map((r) => r.slice('workflows/'.length)))];
+    const tokens = new Set();
+    for (const name of names) {
+        const direct = node_path_1.default.join(workflowsDir, name);
+        let body = null;
+        try {
+            body = node_fs_1.default.readFileSync(direct, 'utf8');
+        }
+        catch {
+            body = null;
+        }
+        if (body === null)
+            continue;
+        for (const tok of parseCallsAgents(body))
+            tokens.add(tok);
+        // Split workflow: union EVERY fragment under the workflow's directory
+        // (steps/, modes/, templates/…) — the parent dispatches into these per
+        // the progressive-disclosure pattern, and spawns live in all of them
+        // (#3798 review: modes/ carried gsd-advisor-researcher's spawn while the
+        // parent only named it incidentally in prose).
+        const fragDir = node_path_1.default.join(workflowsDir, name.slice(0, -3));
+        const walk = (dir) => {
+            let frags;
+            try {
+                frags = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const frag of frags) {
+                const full = node_path_1.default.join(dir, frag.name);
+                if (frag.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!frag.isFile() || !frag.name.endsWith('.md'))
+                    continue;
+                try {
+                    const fragBody = node_fs_1.default.readFileSync(full, 'utf8');
+                    for (const tok of parseCallsAgents(fragBody))
+                        tokens.add(tok);
+                }
+                catch { /* unreadable fragment — skip */ }
+            }
+        };
+        walk(fragDir);
+    }
+    return [...tokens];
+}
+function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR, workflowsDir = DEFAULT_WORKFLOWS_DIR) {
     const manifest = new Map();
     if (!node_fs_1.default.existsSync(commandsDir))
         return manifest;
@@ -153,9 +225,12 @@ function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
         try {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(commandsDir, entry.name), 'utf8');
             manifest.set(stem, parseRequires(content));
-            // Derive agent references from body text
-            const agentRefs = parseCallsAgents(content);
-            manifest.set(`_calls_agents_${stem}`, agentRefs);
+            // Derive agent references from body text + the workflows it delegates to
+            const agentRefs = [
+                ...parseCallsAgents(content),
+                ...workflowAgentRefs(content, workflowsDir),
+            ];
+            manifest.set(`_calls_agents_${stem}`, [...new Set(agentRefs)]);
         }
         catch {
             manifest.set(stem, []);
@@ -823,14 +898,14 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  * agent loop in bin/install.js exactly:
  *   1. applyAgentPathRewrites   (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
  *   2. processAttribution       (Co-Authored-By policy)
- *   3. converter                (runtime-specific frontmatter/body transform)
- *   4. applyAgentFrontmatterExtensions (#2875 Part 2: effort/disallowedTools,
+ *   3. appendAgentTools         (#4032: validated agent_tools grants, before host conversion)
+ *   4. converter                (runtime-specific frontmatter/body transform)
+ *   5. applyAgentFrontmatterExtensions (#2875 Part 2: effort/disallowedTools,
  *      gated by hostBehaviors.agentFrontmatterExtensions — no-op for a runtime
  *      that declares nothing, e.g. every non-Claude runtime today)
- *   5. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
- * When `agentCtx` is absent, only the converter is applied (backward-compat for
- * the feat-1173 synthetic-descriptor tests and the copilot/antigravity paths
- * that handle cross-cutting inside their converters).
+ *   6. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
+ * When `agentCtx` is absent, only global `agent_tools` augmentation and the
+ * converter run; other cross-cutting remains absent for backward compatibility.
  *
  * @param srcAgentsDir    source agents directory (e.g. agents/)
  * @param resolvedProfile profile filter from resolveProfile()
@@ -844,8 +919,7 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  *                        every OTHER converter's contract — converters that don't declare a
  *                        3rd parameter simply never read it.
  * @param isGlobal        install scope passed through to the converter
- * @param agentCtx        optional cross-cutting context (ADR-1235 §1); when absent,
- *                        only the converter is applied (backward compat)
+ * @param agentCtx        optional cross-cutting context (ADR-1235 §1)
  */
 function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx) {
     if (!installFs().existsSync(srcAgentsDir))
@@ -877,6 +951,7 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
     try {
         // Resolve cmdNames once per staging call (not per file) for performance.
         const cmdNames = agentCtx ? _readGsdCommandNames() : [];
+        const agentTools = installModelOverrideResolver.readGsdEffectiveAgentTools(agentCtx?.projectDir ?? agentCtx?.targetDir ?? null);
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -896,25 +971,31 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
             // throws loudly naming the file for a malformed marker, never emitting a
             // half-composed agent.
             content = _composeWorkflow(content, { sourcePath: agentSourcePath });
+            const agentName = _deriveAgentName(entry.name);
+            const grants = [
+                ...(agentTools?.['*'] || []),
+                ...(agentTools?.[agentName] || []),
+            ];
             if (agentCtx) {
                 // #2875 Part 2 / row I3: derived exactly as the inline loop does —
                 // single-sourced via deriveAgentName (runtime-artifact-conversion.cts).
-                const agentName = _deriveAgentName(entry.name);
                 // ADR-1235 §1: pre-converter cross-cutting (matches inline loop order exactly)
                 // Step 1: path rewrites (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
                 content = _applyAgentPathRewrites(content, agentCtx.runtime, agentCtx.pathPrefix);
                 // Step 2: attribution
                 content = _processAttribution(content, agentCtx.attribution);
-                // Step 3: converter (runtime-specific frontmatter/body transform)
+                // Step 3: validated canonical grants, before host conversion.
+                content = _appendAgentTools(content, grants);
+                // Step 4: converter (runtime-specific frontmatter/body transform)
                 content = converter(content, isGlobal, { agentName });
-                // Step 4: frontmatter extensions (effort/disallowedTools; no-op unless
+                // Step 5: frontmatter extensions (effort/disallowedTools; no-op unless
                 // the runtime declares hostBehaviors.agentFrontmatterExtensions)
                 content = _applyAgentFrontmatterExtensions(content, { runtime: agentCtx.runtime, agentName, targetDir: agentCtx.targetDir });
-                // Step 5: normalize colon→hyphen refs (no-op for trivial group)
+                // Step 6: normalize colon→hyphen refs (no-op for trivial group)
                 content = _normalizeAgentBodyForRuntime(content, agentCtx.runtime, cmdNames);
             }
             else {
-                // Backward-compat: only apply the converter (no cross-cutting)
+                content = _appendAgentTools(content, grants);
                 content = converter(content, isGlobal);
             }
             installFs().writeFileSync(node_path_1.default.join(stageDir, entry.name), content, 'utf8');
@@ -1156,6 +1237,7 @@ module.exports = {
     // Shared internals
     parseRequires,
     parseCallsAgents,
+    workflowAgentRefs,
     cleanupStagedSkills,
     // #2322: capability-skill security seams — exported for direct unit-testing
     // and for surface.cts's prune pass (CAPABILITY_SKILL_MARKER parity).

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -48,10 +48,14 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-windsurf-pre-command.js',
     'hooks/gsd-ensure-canonical-path.js',
     'hooks/gsd-graphify-update.sh',
+    // #3662: portable node resolver staged into hooks/ (not itself a lifecycle
+    // hook — managed JS hook commands route through it under --portable-hooks).
+    'hooks/gsd-node-runner.sh',
     'hooks/gsd-phase-boundary.sh',
     'hooks/gsd-prompt-guard.js',
     'hooks/gsd-read-guard.js',
     'hooks/gsd-read-injection-scanner.js',
+    'hooks/gsd-secret-read-guard.js',
     'hooks/gsd-session-state.sh',
     'hooks/gsd-statusline.js',
     'hooks/gsd-update-banner.js',

package/gsd-core/bin/lib/installer-migrations/010-antigravity-retire-confighome-artifacts.cjs

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Installer migration: retire Antigravity's configHome skills/agents surfaces (#3738).
+ *
+ * Antigravity's machine-local discovery scans ~/.gemini/config/{skills,agents}
+ * (antigravity.google/docs/skills, /docs/subagents); the configHome
+ * (~/.gemini/antigravity{,-ide,-cli}) is not scanned for global artifacts, so
+ * skills installed there are silently ignored. Since #3738 the global layout
+ * declares a `home: ".gemini/config"` override for both kinds, and new
+ * installs land in the scanned dir. This migration converges an existing
+ * installation: manifest-managed files under the configHome's skills/ and
+ * agents/ subtrees are removed (modified ones backed up first), unmanifested
+ * files are preserved, and now-empty container directories are retired.
+ *
+ * Scope is GLOBAL only: the local workspace layout (.agents/skills,
+ * .agents/agents) is the documented, still-live surface and is never touched.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. Every emitted action type (`remove-managed`, `backup-and-remove`,
+ *   `remove-empty-dir`) is non-interactive and journaled; none requires a
+ *   user choice, and unknown files never produce an action.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and the antigravity row
+ * of docs/installer-migrations.md#runtime-configuration-contract-registry.
+ */
+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"));
+/** The two retired configHome-relative artifact subpaths. */
+const RETIRED_SUBPATHS = ['skills', 'agents'];
+/** Only GSD-owned top-level entries are retirement candidates. */
+const GSD_PREFIX = 'gsd-';
+const FILE_REASON = 'Antigravity scans ~/.gemini/config/{skills,agents} for global discovery and does not scan the ' +
+    'configHome, so these artifacts are invisible to the runtime (#3738); the same artifacts reinstall ' +
+    "under the global layout's .gemini/config home override";
+const FILE_OWNERSHIP_EVIDENCE = 'pre-#3738 antigravity installs record skills/gsd-*/** and agents/gsd-*.md keys in ' +
+    'gsd-file-manifest.json at the configHome root; the migration only walks gsd--prefixed entries ' +
+    'under the two retired subpaths';
+const DIR_REASON = 'the retired container directory is removed only once every GSD-owned entry inside it is gone; a ' +
+    'directory that still holds an unmanifested user file — or any file-level action that failed to ' +
+    'apply — is left in place by the emptiness re-check';
+const DIR_OWNERSHIP_EVIDENCE = 'skills/ and agents/ at the antigravity configHome root are GSD-installed container directories ' +
+    'from the pre-#3738 layout; removal is gated on emptiness by the shared remove-empty-dir action';
+/**
+ * Recursively collect files and directories under `root/relDir`, never
+ * following a symlink (whether it names a file or a directory) and never
+ * emitting a path that resolves outside `baseResolved`. Mirrors the traversal
+ * guard in migration 009 (`walkPiHooksTree`).
+ */
+function walkTree(root, relDir, baseResolved, files, dirs) {
+    const dir = node_path_1.default.join(root, relDir);
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Never follow a symlink into or through: it must not be traversed,
+        // hashed, or removed, regardless of what it points at.
+        if (entry.isSymbolicLink())
+            continue;
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        const resolved = node_path_1.default.resolve(root, relPath);
+        if (resolved !== baseResolved && !resolved.startsWith(baseResolved + node_path_1.default.sep))
+            continue;
+        if (entry.isDirectory()) {
+            dirs.push(relPath);
+            walkTree(root, relPath, baseResolved, files, dirs);
+        }
+        else if (entry.isFile()) {
+            files.push(relPath);
+        }
+    }
+}
+const migration = {
+    id: '2026-08-26-antigravity-retire-confighome-artifacts',
+    title: "Retire Antigravity's configHome skills/agents surfaces",
+    description: 'Remove manifest-managed skills/gsd-*/ and agents/gsd-*.md under the Antigravity configHome ' +
+        '(~/.gemini/antigravity{,-ide,-cli}) — a location Antigravity does not scan for global discovery — ' +
+        'and retire the now-empty container directories, now that the global layout installs both kinds ' +
+        'under the ~/.gemini/config home override (#3738). Global scope only; the local .agents workspace ' +
+        'surface is untouched.',
+    introducedIn: '1.11.0',
+    runtimes: ['antigravity'],
+    scopes: ['global'],
+    destructive: true,
+    plan: (ctx) => {
+        // Defense in depth ahead of the framework's own runtimes/scope filters:
+        // a claude/kimi/etc. skills/ or agents/ directory is a live install
+        // surface, never a retirement target, and so is antigravity's LOCAL
+        // .agents/skills layout.
+        if (ctx.runtime !== 'antigravity')
+            return [];
+        if (ctx.scope !== 'global')
+            return [];
+        const actions = [];
+        for (const subpath of RETIRED_SUBPATHS) {
+            const surfaceRoot = node_path_1.default.join(ctx.configDir, subpath);
+            let rootLstat;
+            try {
+                rootLstat = node_fs_1.default.lstatSync(surfaceRoot);
+            }
+            catch {
+                continue; // absent -> nothing to retire for this surface, idempotent
+            }
+            // Never follow a symlinked surface root: walking through it could plan
+            // actions against paths outside the config directory entirely.
+            if (rootLstat.isSymbolicLink() || !rootLstat.isDirectory())
+                continue;
+            const baseResolved = node_path_1.default.resolve(ctx.configDir);
+            const files = [];
+            const dirs = [];
+            try {
+                const entries = node_fs_1.default.readdirSync(surfaceRoot, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isSymbolicLink() || !entry.name.startsWith(GSD_PREFIX))
+                        continue;
+                    const relPath = node_path_1.default.posix.join(subpath, entry.name);
+                    if (entry.isDirectory()) {
+                        dirs.push(relPath);
+                        walkTree(ctx.configDir, relPath, baseResolved, files, dirs);
+                    }
+                    else if (entry.isFile()) {
+                        files.push(relPath);
+                    }
+                }
+            }
+            catch {
+                // Unreadable directory: nothing safe to plan for this surface.
+                continue;
+            }
+            for (const relPath of files) {
+                const { classification } = ctx.classifyArtifact(relPath);
+                if (classification === 'managed-pristine') {
+                    actions.push({ type: 'remove-managed', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+                }
+                else if (classification === 'managed-modified') {
+                    actions.push({ type: 'backup-and-remove', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+                }
+                // 'unknown' (user-added, not manifest-recorded): no action, preserved.
+                // 'missing' / 'managed-missing': impossible here — relPath was just
+                // discovered by walking the live filesystem, so it currently exists.
+            }
+            // Deepest directories first, so a child has already been evaluated
+            // (and possibly removed) before its parent's own emptiness is
+            // re-checked by the executor. The surface root itself is appended
+            // last, unconditionally: the executor's own emptiness re-check is what
+            // actually decides whether it goes, not this ordering.
+            const orderedDirs = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
+            orderedDirs.push(subpath);
+            for (const relPath of orderedDirs) {
+                actions.push({
+                    type: 'remove-empty-dir',
+                    relPath,
+                    reason: DIR_REASON,
+                    ownershipEvidence: DIR_OWNERSHIP_EVIDENCE,
+                    // Declared, not derived: classifyArtifact() hashes file contents
+                    // via sha256File(), which throws EISDIR against a directory path.
+                    // These relPaths name directories, so classification is stated
+                    // directly (never 'unknown', so the planner's
+                    // unknown-classification block never fires for them).
+                    classification: 'managed-pristine',
+                    originalHash: null,
+                    currentHash: null,
+                });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;

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

@@ -505,17 +505,20 @@ function acquireInstallMigrationLock(configDir, { timeoutMs = DEFAULT_LOCK_TIMEO
         let lockCreatedByUs = false;
         try {
             fd = node_fs_1.default.openSync(lockPath, 'wx');
-            // Close the open descriptor before writing so the file handle is
-            // released on Windows before the release closure unlinks it.
-            // Write payload via writeFileSync with the path (not the fd) so we
-            // don't hold an open fd across the lifetime of the lock.
-            node_fs_1.default.closeSync(fd);
-            fd = null;
             lockCreatedByUs = true; // we own the file; clean it up on any subsequent error
-            node_fs_1.default.writeFileSync(lockPath, JSON.stringify({
+            // Write the payload through the exclusively-created descriptor: a
+            // second open-by-path here would be a TOCTOU window (CWE-367) where a
+            // co-writer of the directory could symlink-swap the just-created empty
+            // lock file before the payload lands.
+            node_fs_1.default.writeFileSync(fd, JSON.stringify({
                 pid: process.pid,
                 acquiredAt: new Date().toISOString(),
             }) + '\n');
+            // Close before returning so no handle stays open across the lock's
+            // lifetime — Windows cannot unlink a file with an open handle when the
+            // release closure runs.
+            node_fs_1.default.closeSync(fd);
+            fd = null;
             lockCreatedByUs = false; // release closure owns cleanup from here
             return () => {
                 const failures = [];

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

@@ -23,6 +23,9 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { formatDiagnosticToken } = ioMod;
 // ─── Constants ───────────────────────────────────────────────────────────────
 const INTEL_DIR = '.planning/intel';
 const INTEL_FILES = {
@@ -32,6 +35,16 @@ const INTEL_FILES = {
     arch: 'arch-decisions.json',
     stack: 'stack.json',
 };
+/**
+ * ADR-3473 §8.5 / #3885: recursion bound for the intel JSON search walk.
+ * Restored from the retired SDK lineage (`sdk/src/query/intel.ts` at `11918dcc3^`),
+ * lost in the ADR-0174 consolidation. Unlike the original, hitting the ceiling is
+ * NOT reported as a silent "no match" — the walk that stops early sets a
+ * `truncated` flag threaded back up to `intelQuery`'s result (Decision 4: a
+ * routine that discards an input says so). The bound is on DEPTH only; breadth
+ * (sibling count at any given depth) is unaffected.
+ */
+const MAX_JSON_SEARCH_DEPTH = 48;
 // ─── Internal helpers ────────────────────────────────────────────────────────
 /**
  * Ensure the intel directory exists under the given planning dir.
@@ -71,16 +84,42 @@ function intelFilePath(planningDir, filename) {
 }
 /**
  * Safely read and parse a JSON intel file.
- * Returns null if file doesn't exist or can't be parsed.
+ *
+ * Returns null for THREE distinct on-disk states, only one of which is a
+ * "quiet" case (#3885, ADR-3473 §8.5):
+ *   - ABSENT (ENOENT, via platformReadSync returning null): silent — not
+ *     every project has every intel file, and callers already loop over
+ *     the full INTEL_FILES set expecting misses. Never pushed to `errors`.
+ *   - UNREADABLE (EACCES/EIO/... — platformReadSync rethrows anything that
+ *     isn't ENOENT): surfaced, naming the file, when `errors` is supplied.
+ *   - MALFORMED (JSON.parse throws on a file that WAS read successfully):
+ *     also surfaced, naming the file — a corrupt intel file used to read
+ *     identically to "no matches", which is the same defect one layer down.
+ *
+ * `errors` is an optional accumulator so callers that want to thread the
+ * outcome into their own result shape can pass an array and read it back
+ * after the call; callers that omit it keep the prior fold-to-null shape.
  */
-function safeReadJson(filePath) {
+function safeReadJson(filePath, errors) {
+    let raw;
+    try {
+        raw = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
+    }
+    catch (err) {
+        if (errors) {
+            errors.push(`Could not read ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken(err?.message ?? String(err))}`);
+        }
+        return null;
+    }
+    if (raw === null)
+        return null; // ENOENT — genuinely absent, not an error.
     try {
-        const raw = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
-        if (raw === null)
-            return null;
         return JSON.parse(raw);
     }
-    catch {
+    catch (err) {
+        if (errors) {
+            errors.push(`Could not parse ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken(err?.message ?? String(err))}`);
+        }
         return null;
     }
 }
@@ -101,16 +140,17 @@ function hashFile(filePath) {
 }
 /**
  * Search for a term (case-insensitive) in a JSON object's keys and string values.
- * Returns an array of matching entries.
+ * Returns matching entries plus whether the walk hit MAX_JSON_SEARCH_DEPTH.
  */
 function searchJsonEntries(data, term) {
     if (!data || typeof data !== 'object')
-        return [];
+        return { matches: [], truncated: false };
     const entries = data.entries || data;
     if (!entries || typeof entries !== 'object')
-        return [];
+        return { matches: [], truncated: false };
     const lowerTerm = term.toLowerCase();
     const matches = [];
+    const state = { truncated: false };
     for (const [key, value] of Object.entries(entries)) {
         if (key === '_meta')
             continue;
@@ -119,25 +159,40 @@ function searchJsonEntries(data, term) {
             matches.push({ key, value });
             continue;
         }
-        // Check string value match (recursive for objects)
-        if (matchesInValue(value, lowerTerm)) {
+        // Check string value match (recursive for objects/arrays, bounded by depth)
+        if (matchesInValue(value, lowerTerm, 0, state)) {
             matches.push({ key, value });
         }
     }
-    return matches;
+    return { matches, truncated: state.truncated };
 }
 /**
  * Recursively check if a term appears in any string value.
+ *
+ * `depth` counts container unwraps already performed (starts at 0 for the
+ * entry's own value). Strings never fail the ceiling check themselves — only
+ * a container (object/array) refuses to recurse one level deeper once
+ * `depth > MAX_JSON_SEARCH_DEPTH`, at which point `state.truncated` is set so
+ * the caller can report "I stopped looking" rather than a bare "no match".
+ * The bound is on nesting depth only, never on sibling breadth.
  */
-function matchesInValue(value, lowerTerm) {
+function matchesInValue(value, lowerTerm, depth, state) {
     if (typeof value === 'string') {
         return value.toLowerCase().includes(lowerTerm);
     }
     if (Array.isArray(value)) {
-        return value.some(v => matchesInValue(v, lowerTerm));
+        if (depth > MAX_JSON_SEARCH_DEPTH) {
+            state.truncated = true;
+            return false;
+        }
+        return value.some(v => matchesInValue(v, lowerTerm, depth + 1, state));
     }
     if (value && typeof value === 'object') {
-        return Object.values(value).some(v => matchesInValue(v, lowerTerm));
+        if (depth > MAX_JSON_SEARCH_DEPTH) {
+            state.truncated = true;
+            return false;
+        }
+        return Object.values(value).some(v => matchesInValue(v, lowerTerm, depth + 1, state));
     }
     return false;
 }
@@ -150,19 +205,23 @@ function intelQuery(term, planningDir) {
         return disabledResponse();
     const matches = [];
     let total = 0;
+    let truncated = false;
+    const readErrors = [];
     // Search all JSON intel files
     for (const [_key, filename] of Object.entries(INTEL_FILES)) {
         const filePath = intelFilePath(planningDir, filename);
-        const data = safeReadJson(filePath);
+        const data = safeReadJson(filePath, readErrors);
         if (!data)
             continue;
-        const found = searchJsonEntries(data, term);
+        const { matches: found, truncated: fileTruncated } = searchJsonEntries(data, term);
+        if (fileTruncated)
+            truncated = true;
         if (found.length > 0) {
             matches.push({ source: filename, entries: found });
             total += found.length;
         }
     }
-    return { matches, term, total };
+    return { matches, term, total, truncated, read_errors: readErrors };
 }
 /**
  * Report status and staleness of each intel file.
@@ -179,13 +238,14 @@ function intelStatus(planningDir) {
         const filePath = intelFilePath(planningDir, filename);
         const exists = node_fs_1.default.existsSync(filePath);
         if (!exists) {
-            files[filename] = { exists: false, updated_at: null, stale: true };
+            files[filename] = { exists: false, updated_at: null, stale: true, read_error: null };
             overallStale = true;
             continue;
         }
         let updatedAt = null;
         // All intel files are JSON — read _meta.updated_at
-        const data = safeReadJson(filePath);
+        const readErrors = [];
+        const data = safeReadJson(filePath, readErrors);
         if (data && data._meta && data._meta.updated_at) {
             updatedAt = data._meta.updated_at;
         }
@@ -196,7 +256,7 @@ function intelStatus(planningDir) {
         }
         if (stale)
             overallStale = true;
-        files[filename] = { exists: true, updated_at: updatedAt, stale };
+        files[filename] = { exists: true, updated_at: updatedAt, stale, read_error: readErrors[0] ?? null };
     }
     return { files, overall_stale: overallStale };
 }
@@ -207,9 +267,15 @@ function intelDiff(planningDir) {
     if (!isIntelCapabilityActive(planningDir))
         return disabledResponse();
     const snapshotPath = intelFilePath(planningDir, '.last-refresh.json');
-    const snapshot = safeReadJson(snapshotPath);
+    const readErrors = [];
+    const snapshot = safeReadJson(snapshotPath, readErrors);
     if (!snapshot) {
-        return { no_baseline: true };
+        // #3885 (ADR-3473 §8.5): `no_baseline: true` stays true for BOTH a
+        // genuinely-never-snapshotted project (ENOENT, read_error stays null)
+        // AND a present-but-unreadable/malformed snapshot — collapsing those
+        // two into a bare `no_baseline: true` would manufacture "you've never
+        // run a refresh" out of a read failure. `read_error` names which one.
+        return { no_baseline: true, read_error: readErrors[0] ?? null };
     }
     const prevHashes = snapshot.hashes || {};
     const changed = [];
@@ -374,7 +440,9 @@ function intelApiSurface(planningDir) {
     const intelPath = ensureIntelDir(planningDir);
     const apiMapPath = node_path_1.default.join(intelPath, INTEL_FILES.apis);
     const outputPath = node_path_1.default.join(intelPath, 'API-SURFACE.md');
-    const data = safeReadJson(apiMapPath);
+    const readErrors = [];
+    const data = safeReadJson(apiMapPath, readErrors);
+    const readError = readErrors[0] ?? null;
     const entries = (data && data.entries && typeof data.entries === 'object')
         ? Object.entries(data.entries)
         : [];
@@ -392,7 +460,14 @@ function intelApiSurface(planningDir) {
     lines.push('> Generated from `.planning/intel/api-map.json`. Do not edit by hand.');
     lines.push('');
     if (symbolCount === 0) {
-        lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
+        if (readError) {
+            // #3885: a read/parse failure is NOT "not yet populated" — say so,
+            // rather than manufacturing the wrong reason for the empty surface.
+            lines.push(`> **Incomplete:** ${readError}`);
+        }
+        else {
+            lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
+        }
         lines.push('> Treat absence here as "unknown", not "does not exist".');
         lines.push('');
     }
@@ -414,7 +489,7 @@ function intelApiSurface(planningDir) {
         }
     }
     (0, shell_command_projection_cjs_1.platformWriteSync)(outputPath, lines.join('\n'));
-    return { written: outputPath, symbolCount, stale };
+    return { written: outputPath, symbolCount, stale, read_error: readError };
 }
 /**
  * Patch _meta.updated_at in a JSON intel file to the current timestamp.