jev-agent-tools 0.2.0 → 0.3.0

package/docs/tools/jev_locate_in_file.md

@@ -18,6 +18,7 @@ Code splits the file into declarations or sections and constructs a choice over
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `path` | Required nonempty string | One repository-relative file, at least 19,000 bytes. |
 | `goal` | Required nonempty string | Sentence describing the behavior you need to find. |
 
@@ -38,10 +39,14 @@ Illustrative call with a fictional repository path, not a recorded execution:
 
 A result names `path:start-end`, a label, probability and the next read. Above 0.7 an unmarked range is a verdict: read it. From 0.4 through 0.7, unsure lists the two best ranges by probability: read both, not an arbitrary next section. Below 0.4 the tool narrows to three leading candidates plus none and judges again, retaining the original unsure band. Option-order sensitivity can also leave the result unsure. `none` means no supplied section fits: search elsewhere or clarify the goal. See [shared result reading](../../README.md#read-the-results).
 
+The versioned report preserves actual primary/control values and their fresh/cache source. Missing required control answers produce unjudged work rather than a synthesized range or probability. Typed diagnostics retain parsing/window omissions and native next actions, including searching elsewhere for a judged `none`.
+
 ## Limits and failure behavior
 
 Small files are refused with direct-read guidance. Whole-file admission is bounded by 320,000 characters and 1,280,000 bytes; larger files take the streamed-window path, not silent whole-file truncation. Window serialization, fallback section sizes, parsing support and choice cardinality are separately bounded. Unreadable or invalid evidence, missing configuration and exhausted session budgets are reported rather than producing a range verdict. Missing optional Python grammar is named with installation guidance. A selected window does not prove every relevant declaration was inspected.
 
+The serialized judgment budget includes per-call evidence provenance. Block planning, excerpt allocation and full-text refinement reserve that metadata capacity before selecting evidence; provenance never silently pushes an otherwise planned request past admission. Selected blocks still require at least two sections and obey the choice limit.
+
 ## Host differences
 
 omp `read` already outlines code files: use this tool when that outline does not tell you which range serves your goal. Both hosts use the same judgment protocol; omp marks the tool read-only.

package/docs/tools/jev_select_tests.md

@@ -20,6 +20,7 @@ Residual exported-unit checks concern changed units not exercised by any discove
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `base` | Optional nonempty Git ref, default `HEAD` | Compare the current tree with this revision. |
 | `paths` | Optional array of nonempty strings, default discovered inventory | Candidate test files or globs, not changed source paths. |
 | `witnesses` | Optional `"off"`, `"auto"` (default), `"on"` | Controls residual coverage checks; test pointers have no witnesses. |
@@ -27,6 +28,8 @@ Residual exported-unit checks concern changed units not exercised by any discove
 
 Unknown fields and unresolved refs are rejected with guidance. Repository-relative evidence paths are confined to the repository; internal URLs are not file inputs. Narrowing candidate paths also narrows the inventory to which coverage observations apply.
 
+Each requested criterion reports its matches and any excluded or unmatched inventory. Partial matches keep the matched selection and identify the unmatched criteria; zero matches are not proof of no affected tests. Changed files outside the supported dependency graph retain conservative widening, with the triggering paths named. Runner commands remain static plans and use the admitted root.
+
 ## Example
 
 Illustrative call with fictional repository paths, not a recorded execution:
@@ -44,7 +47,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 Inspect selected scenarios and the returned runner commands, then execute them yourself. A scenario is selected when `1 - p(none) >= 0.5`; missing answers are selected too. If at least 80% of a file's scenarios are selected, names are uncertain or counts unknown, the command runs the whole file instead of a fragile name filter. Commands remain separate when runner context differs.
 
-`fallback: all` means conservative selection, not that Jev confirmed every scenario is affected. `changed, run by no discovered test` is limited to discovery evidence; do not call it repository-wide uncovered behavior. Read unsure or unsupported-runner limits and follow the named manual check. See [shared result reading](../../README.md#read-the-results).
+Static selection identifies its deterministic reason separately from fresh/cache Jev judgments. Conservative fallback preserves tests when judgments are unavailable; it is not confirmation that every scenario is affected. Residual absence is a derived reservation linked to retained coverage items or the considered inventory, not an extra requested judgment or fabricated probability. It does not establish repository-wide uncovered behavior. Read material limits and follow the named native action. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-agent-tools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "mcpName": "io.github.NomenAK/jev-agent-tools",

package/rules/jev-ask.md

@@ -1,4 +1,25 @@
 ---
 alwaysApply: true
 ---
-jev_ask: before you conclude that a failure is a bug in the code, a wrong test or the environment, or that a plan matches the docs, pass the files to jev_ask and weigh its answer against your own reading
+<!-- Generated policy 2026-10-03.1 from src/texts/instructions.ts; run node scripts/generate-instructions.ts after editing the source. -->
+Use Jev for a bounded semantic judgment when its answer could change an open decision or focus the next inspection, and the relevant evidence is available. Use decisive reading, search or authorized execution directly when it settles the question. Exact lookup, counting and runtime causality belong to native tools. A Jev call is not a prerequisite for a conclusion, a review or task completion; no explanation is needed for choosing native tools.
+
+Before a chosen call, identify the open decision and supply only the evidence needed for a bounded question; a complete prior analysis is not required. Ask about one positive, self-contained observable fact per claim, with its sources, and show both sides of a comparison.
+- Failure: relevant output, the failing test and the implementation it exercises; output alone is a lead, not a bug-versus-wrong-test diagnosis. Include configuration or runtime evidence when the hypothesis depends on it. A static judgment does not establish runtime causality.
+- Change: current evidence and the earlier reference via base. Use the checkout/root corresponding to the work and admitted by the tool; another clone is not the same context.
+- Plan/documentation: precise observable commitments and the passages that constrain them. Local confirmation does not establish that omitted obligations were searched.
+- Selection/review: compatible inventory, references and configuration. Suggested commands are not executed commands; existing tests need not cover a new scenario. Read the diff natively for its contents, not as proof of safety or global coverage.
+
+After an unavailable, refused or out-of-scope result, continue natively within the existing permissions; do not widen sharing or confinement to obtain a judgment. For uncertainty or missing evidence, inspect or obtain the decisive piece, or leave the conclusion open. Revisit Jev only when new evidence, a material context change or a new useful question makes the judgment useful; rewording unchanged evidence is not a reason to retry. There is no retry quota for genuinely changed evidence, and no certification is needed once decisive evidence settles the question. A reached cap or an unjudged result is not evidence of safety or zero affected tests.
+
+jev_check_diff: Review a stable diff for semantic risks, stale documentation or specification drift when that review can inform an open decision. Read the diff natively when you need its contents. Choose risk, docs or spec for the question at hand; neither risk followed by docs nor a Jev review before done is required. Findings are leads within the inspected scope, not proof of global safety or completeness.
+
+Report current conclusions first, then decisive evidence, origin and scope, then material reservations. Established means supported by relevant decisive evidence; a reported check remains explicitly reported, not observed execution. Distinguish native reading/execution, Jev's static judgment and testimony. A call count or global status is not proof.
+If native evidence settles the same scope and context after a Jev uncertainty, attribute the current conclusion to that evidence; old unsure or abstain results need not be recited as current reservations. A later Jev confirmation is attributed to Jev and retains its static limits. Independent reservations survive either resolution.
+Where an uncertainty actually returned by Jev remains material, explicitly say “Jev did not confirm X”, identify the missing evidence or guarantee, its known or indeterminate impact and the evidence to obtain. Preserve that reservation in the main text, summary and recommendation. Name native reservations and unjudged work as such, not as Jev uncertainty. Unresolved contradiction, stale evidence or a different checkout/base/scenario remains a reservation; the latest favorable answer does not win by default.
+Keep material limits in the main text, not only behind a link. Do not generalize a checked scenario into a universal guarantee. Separate relevant unestablished hypotheses from observations; omit irrelevant hypotheses. Explain unavailable historical causes only when material to action or requested, without inventing causality.
+Use existing history references when useful or requested; no exhaustive historical relay, persistent register or History block is required. A requested audit details available steps separately from the current state and does not reopen settled conclusions. Preserve existing traces; identify unavailable traces when they limit evidence or audit, without reconstructing evidence, executions or call counts. pi/OMP may reference an existing trace; MCP references must be client-accessible or explicitly unavailable.
+
+pi and OMP retain an automatic, opt-out documentation check at task completion (JEV_TOOLS_AUTO_DOCS=0 disables it). It is a host feature, not an agent requirement to call Jev. Inspect any flagged sentence against the change and update it or explain with evidence why it remains correct. The check is limited and does not certify documentation completeness or demonstrated usefulness. A flagged sentence does not require a second call or recursive reviews.
+
+Evidence passed to jev_* tools leaves the machine for the configured endpoint. Review its data handling; share only authorized evidence, never secrets or credentials. Host/client approvals still apply. jev_ask commands run with normal shell permissions and no sandbox; prefer read-only commands. Tool choice does not relax quality, proof, approval or confidentiality obligations.

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.NomenAK/jev-agent-tools",
   "title": "Jev agent tools",
   "description": "Evidence-oriented code questions, diff review and test selection via a Jev endpoint.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "url": "https://github.com/NomenAK/jev-tools",
     "source": "github"
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "jev-agent-tools",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/src/adapters/ask-files.ts

@@ -23,7 +23,7 @@ export async function collectAskFiles(
   paths: readonly string[],
   signal?: AbortSignal,
   exec?: GitExec,
-): Promise<Result<{ files: AskFile[]; skipped: string[] }>> {
+): Promise<Result<{ files: AskFile[]; skipped: string[]; secret: string[] }>> {
   if (!paths.length)
     return {
       ok: false,
@@ -42,6 +42,7 @@ export async function collectAskFiles(
       };
   }
   const skipped = new Set<string>();
+  const secret = new Set<string>();
   const candidates = new Set<string>();
   try {
     let inventory: Set<string> | undefined;
@@ -63,7 +64,9 @@ export async function collectAskFiles(
         inventory,
       );
       if (!admission.ok) {
-        skipped.add(`${path} (${admission.error})`);
+        const entry = `${path} (${admission.error})`;
+        skipped.add(entry);
+        if (admission.cause === "secret_pattern") secret.add(entry);
         return;
       }
       if (path.split("/").some((part) => excludedDirectories.has(part)))
@@ -229,7 +232,12 @@ export async function collectAskFiles(
         };
       }
     }
-    return { ok: true, files, skipped: [...skipped].sort() };
+    return {
+      ok: true,
+      files,
+      skipped: [...skipped].sort(),
+      secret: [...secret].sort(),
+    };
   } catch (error) {
     return { ok: false, error: `Cannot expand paths: ${String(error)}` };
   }

package/src/adapters/ask-proof.ts

@@ -1,14 +1,15 @@
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.ts";
 import type { GitExec } from "../core/git.ts";
 import type { ImportSource } from "../core/imports.ts";
 import type { Result } from "../result.ts";
-import { collectFiles } from "./files.ts";
+import { checkFileAdmission, collectFiles } from "./files.ts";
 import { verifyGitUtf8 } from "./utf8.ts";
 
 export interface AskRepository {
   root: string;
   known: ReadonlySet<string>;
+  beforeKnown: ReadonlySet<string>;
   baseSha?: string;
   read(path: string): Promise<Result<ImportSource>>;
   readBefore(path: string): Promise<Result<{ text: string | null }>>;
@@ -69,18 +70,20 @@ export async function collectAskRepository(
     for (const path of ignored.stdout.split("\0")) known.delete(path);
     const baseSha = revision?.stdout.trim();
     const basePaths = baseSha
-      ? await exec(
-          "git",
-          ["ls-tree", "-r", "--name-only", "-z", baseSha],
-          gitOptions,
-        )
+      ? await exec("git", ["ls-tree", "-r", "-z", baseSha], gitOptions)
       : undefined;
     if (basePaths && (basePaths.code !== 0 || basePaths.killed))
       return {
         ok: false,
         error: basePaths.stderr || "Cannot list base paths.",
       };
-    const beforeKnown = new Set(basePaths?.stdout.split("\0").filter(Boolean));
+    const beforeEntries = new Map(
+      (basePaths?.stdout.split("\0").filter(Boolean) ?? []).map((entry) => [
+        entry.slice(entry.indexOf("\t") + 1),
+        entry,
+      ]),
+    );
+    const beforeKnown = new Set(beforeEntries.keys());
     const reads = new Map<string, Promise<Result<ImportSource>>>();
     const beforeReads = new Map<
       string,
@@ -90,6 +93,7 @@ export async function collectAskRepository(
       ok: true,
       root,
       known,
+      beforeKnown,
       baseSha,
       read(path) {
         let pending = reads.get(path);
@@ -117,9 +121,53 @@ export async function collectAskRepository(
         let pending = beforeReads.get(path);
         if (!pending) {
           pending = (async () => {
-            if (!baseSha || !beforeKnown.has(path))
-              return { ok: true as const, text: null };
             try {
+              if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+                return {
+                  ok: false as const,
+                  cause: "forbidden_path" as const,
+                  error: `Path must remain inside the repository: ${path}.`,
+                };
+              const admission = await checkFileAdmission(root, path);
+              if (!admission.ok) return admission;
+              const ignoredPath = await exec(
+                "git",
+                ["check-ignore", "--no-index", "--", path],
+                gitOptions,
+              );
+              if (ignoredPath.killed || ![0, 1].includes(ignoredPath.code))
+                return {
+                  ok: false as const,
+                  cause: "git_failure" as const,
+                  error: `${path}: historical admission unavailable`,
+                };
+              if (ignoredPath.code === 0)
+                return {
+                  ok: false as const,
+                  cause: "ignored_path" as const,
+                  error: `${path}: gitignored: not sent to Jev`,
+                };
+              if (!baseSha)
+                return {
+                  ok: false as const,
+                  error: `${path}: comparison base unavailable`,
+                };
+              if (!beforeKnown.has(path))
+                return known.has(path)
+                  ? { ok: true as const, text: null }
+                  : {
+                      ok: false as const,
+                      error: `${path}: not in current or comparison base inventory`,
+                    };
+              const entry = beforeEntries.get(path) ?? "";
+              if (!/^(?:100644|100755) blob /.test(entry))
+                return {
+                  ok: false as const,
+                  cause: entry.startsWith("120000 ")
+                    ? ("symlink" as const)
+                    : ("file_unavailable" as const),
+                  error: `${path}: not a regular file at comparison base: not sent to Jev`,
+                };
               const object = await exec(
                 "git",
                 [
@@ -172,10 +220,20 @@ export async function collectAskRepository(
                   ok: false as const,
                   error: `before evidence unavailable for ${path}`,
                 };
+              if (loaded.stdout.includes("\0"))
+                return {
+                  ok: false as const,
+                  cause: "binary_or_non_utf8" as const,
+                  error: `${path}: binary content: not sent to Jev`,
+                };
               const decoded = verifyGitUtf8(loaded.stdout, id, size);
               return decoded.ok
                 ? decoded
-                : { ok: false as const, error: `${path}: ${decoded.error}` };
+                : {
+                    ok: false as const,
+                    cause: "binary_or_non_utf8" as const,
+                    error: `${path}: ${decoded.error}`,
+                  };
             } catch (error) {
               return { ok: false as const, error: String(error) };
             }

package/src/adapters/command.ts

@@ -32,12 +32,47 @@ export interface CommandOutput {
   compressed: boolean;
   truncated: boolean;
 }
+const TRUNCATION_MARK = `…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`;
+/** Shortest key prefix worth redacting when a line cut leaves only its start. */
+const SECRET_PREFIX_MIN = 4;
+/**
+ * Replace every occurrence of `secret` in `text`, counting replacements. A
+ * line cut at OUTPUT_LINE_MAX_CHARS can end inside the key; that trailing key
+ * prefix is redacted too.
+ */
+export function redactSecret(
+  text: string,
+  secret: string | undefined,
+): { text: string; count: number } {
+  if (!secret) return { text, count: 0 };
+  const parts = text.split(secret);
+  let result = parts.join("[redacted]");
+  let count = parts.length - 1;
+  if (result.endsWith(TRUNCATION_MARK)) {
+    const kept = result.slice(0, -TRUNCATION_MARK.length);
+    const min = Math.min(SECRET_PREFIX_MIN, secret.length);
+    for (
+      let length = Math.min(secret.length - 1, kept.length);
+      length >= min;
+      length--
+    ) {
+      if (kept.endsWith(secret.slice(0, length))) {
+        result = `${kept.slice(0, -length)}[redacted]${TRUNCATION_MARK}`;
+        count++;
+        break;
+      }
+    }
+  }
+  return { text: result, count };
+}
 export async function captureCommand(
   exec: GitExec,
   cwd: string,
   command: string,
   timeoutS = ASK_TIMEOUT_S,
   signal?: AbortSignal,
+  /** Configured Jev API key, replaced in the captured command and output. */
+  secret?: string,
 ): Promise<
   Result<{
     output: CommandOutput;
@@ -48,9 +83,19 @@ export async function captureCommand(
     selectedPassages: boolean;
     assertion: boolean;
     targets: FailureTarget[];
-  }>
+    /** Occurrences of `secret` replaced with `[redacted]`. */
+    redactions: number;
+  }> & {
+    commandExecution: "not_started" | "unknown" | "finished";
+    commandExitCode?: number | null;
+    commandTimedOut?: boolean;
+  }
 > {
   const directory = await mkdtemp(join(tmpdir(), "jev-output-"));
+  let commandExecution: "not_started" | "unknown" | "finished" = "not_started";
+  let completion:
+    | { commandExitCode: number | null; commandTimedOut: boolean }
+    | undefined;
   try {
     await chmod(directory, 0o700);
     const stdoutPath = join(directory, "stdout");
@@ -65,7 +110,14 @@ export async function captureCommand(
     try {
       const shell = resolveShell();
       // Fail closed: never spawn a bare name that PATH could resolve to WSL.
-      if (!shell.ok) throw new Error(shell.error);
+      if (!shell.ok)
+        return {
+          ok: false,
+          cause: "file_unavailable",
+          commandExecution: "not_started",
+          error: shell.error,
+        };
+      commandExecution = "unknown";
       executed = await exec(
         shell.executable,
         [
@@ -78,26 +130,18 @@ export async function captureCommand(
         ],
         { cwd, timeout: timeoutS * 1000, signal },
       );
+      commandExecution = "finished";
+      completion = {
+        commandExitCode: executed.killed ? null : executed.code,
+        commandTimedOut: executed.killed,
+      };
     } catch (error) {
       signal?.throwIfAborted();
       return {
-        ok: true,
-        output: {
-          command,
-          exit_code: null,
-          timed_out: false,
-          stdout: "",
-          stderr: `Command executable unavailable: ${String(error)}`,
-          compressed: true,
-          truncated: false,
-        },
-        originalBytes: 0,
-        compressedChars: 0,
-        lineOmittedChars: 0,
-        shapeLimitExceeded: false,
-        selectedPassages: false,
-        assertion: false,
-        targets: [],
+        ok: false,
+        cause: "file_unavailable",
+        commandExecution,
+        error: `Command executable unavailable: ${String(error)}`,
       };
     }
     signal?.throwIfAborted();
@@ -119,6 +163,9 @@ export async function captureCommand(
     if (sizes.some((size) => size > OUTPUT_FILE_MAX_BYTES))
       return {
         ok: false,
+        cause: "evidence_too_large",
+        commandExecution: "finished",
+        ...completion,
         error: `output exceeded ${OUTPUT_FILE_MAX_BYTES} bytes per stream; narrow command`,
       };
     const targets: FailureTarget[] = [];
@@ -128,19 +175,23 @@ export async function captureCommand(
     let lineOmittedChars = 0;
     let shapeLimitExceeded = false;
     const texts: string[] = [];
+    let redactions = 0;
+    const redacted = (text: string): string => {
+      const result = redactSecret(text, secret);
+      redactions += result.count;
+      return result.text;
+    };
     for (const [index, path] of [stdoutPath, stderrPath].entries()) {
       if (!sizes[index]) {
-        texts.push(index === 0 ? executed.stdout : executed.stderr);
+        texts.push(redacted(index === 0 ? executed.stdout : executed.stderr));
         continue;
       }
       const frequencies = new Map<string, number>();
       let shapeLimit = false;
       for await (const raw of outputLines(path, signal)) {
         signal?.throwIfAborted();
-        const line = cleanOutput(raw);
-        linesTruncated ||= raw.endsWith(
-          `…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`,
-        );
+        const line = redactSecret(cleanOutput(raw), secret).text;
+        linesTruncated ||= raw.endsWith(TRUNCATION_MARK);
         const shape = lineShape(line);
         if (
           !frequencies.has(shape) &&
@@ -187,17 +238,17 @@ export async function captureCommand(
         lineOmittedChars += chars;
       })) {
         signal?.throwIfAborted();
-        linesTruncated ||= raw.endsWith(
-          `…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`,
-        );
-        compressor.line(cleanOutput(raw));
+        linesTruncated ||= raw.endsWith(TRUNCATION_MARK);
+        // Redact before compression, failure windows and state assembly.
+        const line = redacted(cleanOutput(raw));
+        compressor.line(line);
         if (!failureSeen) {
-          failureWindow.push(cleanOutput(raw));
+          failureWindow.push(line);
           if (failureWindow.length > OUTPUT_FAILURE_WINDOW_LINES + 1)
             failureWindow.shift();
           if (isAnchor(raw)) failureSeen = true;
         } else if (afterFailure++ < OUTPUT_FAILURE_WINDOW_LINES) {
-          failureWindow.push(cleanOutput(raw));
+          failureWindow.push(line);
           if (!secondSeen && afterFailure > 1 && isFailingTestsHeader(raw)) {
             secondSeen = true;
             afterSecond = 0;
@@ -206,10 +257,10 @@ export async function captureCommand(
           if (isFailingTestsHeader(raw)) {
             secondSeen = true;
             afterSecond = 0;
-            failureWindow.push(cleanOutput(raw));
+            failureWindow.push(line);
           }
         } else if (afterSecond++ < OUTPUT_FAILURE_WINDOW_LINES) {
-          failureWindow.push(cleanOutput(raw));
+          failureWindow.push(line);
         }
       }
       compressor.finish();
@@ -220,8 +271,10 @@ export async function captureCommand(
     }
     return {
       ok: true,
+      commandExecution: "finished",
+      ...completion,
       output: {
-        command,
+        command: redacted(command),
         exit_code: executed.killed ? null : executed.code,
         timed_out: executed.killed,
         stdout: texts[0] ?? "",
@@ -236,6 +289,16 @@ export async function captureCommand(
       selectedPassages: false,
       assertion: signature === "assertion",
       targets,
+      redactions,
+    };
+  } catch (error) {
+    signal?.throwIfAborted();
+    return {
+      ok: false,
+      cause: "file_unavailable",
+      commandExecution,
+      ...completion,
+      error: `Command capture unavailable: ${String(error)}`,
     };
   } finally {
     await rm(directory, { recursive: true, force: true });

package/src/adapters/docs.ts

@@ -5,6 +5,7 @@ import {
 } from "../core/docs.ts";
 import type { GitExec } from "../core/git.ts";
 import type { Result } from "../result.ts";
+import type { Cause } from "../result-types.ts";
 import {
   checkFileAdmission,
   openRepoFile,
@@ -20,7 +21,7 @@ export interface DocsInventory {
   cwd: string;
   files: DocsSource[];
   tracked: ReadonlySet<string>;
-  limits: { path: string; reason: string }[];
+  limits: { path: string; reason: string; cause?: Cause }[];
   read: (path: string) => Promise<DocsSource | undefined>;
 }
 /** Inventory paths eagerly, but load only Markdown/configuration and subsequently reached sources. */
@@ -37,6 +38,7 @@ export async function collectDocsInventory(
   if (root.code || root.killed)
     return {
       ok: false,
+      cause: signal?.aborted ? "cancelled" : "git_failure",
       error: root.stderr.trim() || "Repository root not found.",
     };
   cwd = root.stdout.trim();
@@ -48,6 +50,7 @@ export async function collectDocsInventory(
   if (list.code || list.killed)
     return {
       ok: false,
+      cause: signal?.aborted ? "cancelled" : "git_failure",
       error: list.stderr.trim() || "Unable to inventory tracked files.",
     };
   const tracked = new Set(list.stdout.split("\0").filter(Boolean));
@@ -70,7 +73,11 @@ export async function collectDocsInventory(
           inventory: tracked,
         });
         if (!opened.ok) {
-          limits.push({ path, reason: opened.error });
+          limits.push({
+            path,
+            reason: opened.error,
+            ...(opened.cause ? { cause: opened.cause } : {}),
+          });
           return undefined;
         }
         const handle = opened.handle;
@@ -168,18 +175,22 @@ export function docsDeclarationSearch(
             const path = candidates[index++];
             if (path === undefined) return;
             const location = await resolveInsideRepo(inventory.cwd, path);
-            const admitted =
-              location.ok &&
-              (
-                await checkFileAdmission(
+            const admission = location.ok
+              ? await checkFileAdmission(
                   inventory.cwd,
                   location.rel,
                   exec,
                   signal,
                   inventory.tracked,
                 )
-              ).ok;
-            if (admitted) paths.push(path);
+              : location;
+            if (admission.ok) paths.push(path);
+            else if (admission.cause === "secret_pattern")
+              inventory.limits.push({
+                path,
+                reason: admission.error,
+                cause: admission.cause,
+              });
           }
         }),
       );
@@ -188,12 +199,20 @@ export function docsDeclarationSearch(
     const paths = await admittedPaths;
     if (!paths.length) return new Map();
     const patterns = ["-e", docsDeclarationPattern(names)];
-    const result = await exec("rg", ["--json", ...patterns, "--", ...paths], {
-      cwd: inventory.cwd,
-      timeout: TIMEOUT_MS,
-      signal,
-    });
-    if (result.killed || (result.code !== 0 && result.code !== 1)) {
+    let result:
+      | { stdout: string; stderr: string; code: number; killed: boolean }
+      | undefined;
+    try {
+      result = await exec("rg", ["--json", ...patterns, "--", ...paths], {
+        cwd: inventory.cwd,
+        timeout: TIMEOUT_MS,
+        signal,
+      });
+    } catch {
+      // A missing or unstartable rg is an unavailable search, not a failure.
+      signal?.throwIfAborted();
+    }
+    if (!result || result.killed || (result.code !== 0 && result.code !== 1)) {
       inventory.limits.push({
         path: "documentation",
         reason: "declaration search unavailable",