jev-agent-tools 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -9,6 +9,41 @@ modules are not a stable library API.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-05
+
+### Breaking
+
+- `JEV_TOOLS_URL` (and saved or flag URLs) with plain `http:` is refused unless the host is `127.0.0.1`, `::1` or `localhost`; use `https:`. The configuration error shows neither the URL nor the key and occurs before any request.
+- Files whose base name matches `.env`, `.env.*`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*` or `secrets*` (any depth, case-insensitive; `.env.example`, `.env.sample` and `.env.template` excepted) are refused before reading on every evidence path, including diff units, test inventory, find, locate, ask-files and the pi/omp documentation hook. Each refusal is a named exclusion with the new cause `secret_pattern`; a question that explicitly requires such a file stays unjudged. There is no override.
+
+### Security
+
+- `jev_ask` commands and the Windows PowerShell ACL helper no longer inherit `JEV_TOOLS_API_KEY`. The configured key value (environment or saved configuration) is replaced with `[redacted]` in command output before state assembly, including a key prefix left where a long output line is cut, and the number of replacements is reported as a limitation.
+
+### Added
+
+- Optional `root` on all six tools, limited to the initial repository's exact Git root or registered live worktrees with the same common directory; invalid overrides refuse before evidence, commands, cache or judgments.
+- Versioned typed reports for every tool outcome, including refused and unjudged work: evidence context, item provenance, scoped diagnostics/actions and separate requested-result, HTTP, cache, control, passage and cost accounting.
+- MCP output schema and structured results from protocol 2025-06-18 onward, with self-contained text for older clients and per-request version isolation.
+
+### Changed
+
+- Explicit evidence selectors, rather than ordinary lexical mentions, govern missing-evidence exclusions. Canonical file versions are serialized once with alias metadata; before/current evidence remains distinct and missing requirements affect their own question group unless global.
+- Host guidance now makes Jev discretionary, shares versioned canonical fragments across pi/omp/MCP, and reports current conclusions with evidence provenance and material reservations. The pi/omp opt-out documentation hook remains; MCP requires no manual replacement call.
+- Human output is a projection of the typed report. Static/fallback selection and unavailable judgments never acquire fabricated probabilities; cached results are distinct from fresh requests and unknown cost is not zero.
+
+### Fixed
+
+- Historical-only and deleted-file evidence resolution, supplied-file basename precedence and canonical file-count admission without duplicated alias content.
+- Command output reaches bounded passage selection before immutable-evidence budget refusal, including base snapshots and import closure; reports preserve actual command execution/cwd even when later collection fails.
+- Selection reports distinguish unmatched candidate criteria, partial matches, excluded inventory and named conservative-widening triggers from absence of affected tests.
+- Review reports retain documentation completeness/collection reservations and risk/coverage witness diagnostics. Residual absence summaries remain derived observations within the considered inventory, not extra judgments or global coverage claims.
+- Recovery actions preserve the actual evidence/control limitation instructions rather than generic repetition advice.
+- Local-caller reports preserve their independent unsure/abstain bands and matching probabilities; specification drift remains one pointer decision rather than duplicated judgments for every candidate unit.
+- MCP malformed tool arguments remain JSON-RPC invalid-parameter errors, separate from well-formed calls refused by evidence admission.
+- Every judgment stage binds cache identity and serialized admission to its admitted root/base context, including auxiliary command passages. Locate planning reserves that metadata capacity before allocating evidence.
+- Historical selectors use protected base reads for ignored paths, symlinks, non-text content and deleted files; current/base versions share the distinct-file ceiling without bypassing rejected admissions.
+
 ## [0.2.0] - 2026-10-03
 
 ### Added
@@ -142,7 +177,8 @@ Tagged but never published to npm: the unscoped package name was rejected.
 
 Tagged but never published to npm: the publish workflow failed before upload.
 
-[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/NomenAK/jev-tools/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/NomenAK/jev-tools/compare/v0.1.4...v0.2.0
 [0.1.4]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/NomenAK/jev-tools/compare/v0.1.0...v0.1.3

package/CONTRIBUTING.md

@@ -18,11 +18,14 @@ npm run typecheck
 npm run build
 npm run check:imports
 npm run lint
+node scripts/generate-instructions.ts --check
 npm test
 ```
 
 `npm run build` compiles only the MCP server into `dist/` (git-ignored); `npm pack` runs it automatically. To try the server against a checkout, see [From a clone](docs/mcp.md#from-a-clone). CI packs the package and runs `node scripts/check-mcp-package.ts <tarball>`: it installs the tarball into an empty directory, checks modern discovery and all advertised legacy handshakes, lists the six tools with their schemas and caching fields, and runs `jev_ask` through a local synthetic HTTP endpoint. This verifies installed integration, not live model accuracy. Linux runs the full offline suite; native Windows and macOS jobs run targeted MCP, process, configuration and packaging checks.
 
+Agent policy and result-reading guidance are versioned in `src/texts/instructions.ts`. After changing them, run `node scripts/generate-instructions.ts` to update the checked-in omp rule and MCP project block; `--check` verifies that those copies remain synchronized. Keep host differences explicit rather than maintaining independent policy text.
+
 ## Releases
 
 Maintainers release by pushing a `vX.Y.Z` tag on reviewed `main`. Before tagging, set the same version in `package.json`, in both `version` fields of `server.json`, and in a `CHANGELOG.md` section; `test/server-json.test.ts` fails if they drift. [`publish.yml`](.github/workflows/publish.yml) then packs once, checks the packed MCP server, publishes the approved tarball to npm with trusted publishing, publishes `server.json` to the MCP Registry with GitHub OIDC, and creates a draft GitHub Release. Each publication step skips a version that already exists with the same content and fails on anything inconclusive.

package/README.md

@@ -13,15 +13,15 @@ Install through your host's package manager, or register the MCP server with an
 ### pi
 
 ```sh
-pi install npm:jev-agent-tools@0.2.0
+pi install npm:jev-agent-tools@0.3.0
 # Project-local installation:
-pi install -l npm:jev-agent-tools@0.2.0
+pi install -l npm:jev-agent-tools@0.3.0
 ```
 
 ### omp
 
 ```sh
-omp plugin install jev-agent-tools@0.2.0
+omp plugin install jev-agent-tools@0.3.0
 ```
 
 ### Any MCP client
@@ -45,7 +45,7 @@ Since version 0.2.0, the package also ships `jev-agent-tools-mcp`, a stdio MCP s
 
 On Windows most clients start commands without a shell, so use `"command": "cmd"` with `"/c", "npx"` at the start of `args`. The [MCP setup guide](docs/mcp.md) has per-client files, CLI commands, variable interpolation, verification and troubleshooting. Releases are also listed in the official MCP Registry as `io.github.NomenAK/jev-agent-tools`. Add the [agent instructions](docs/agent-instructions.md) to `CLAUDE.md`, `AGENTS.md` or a Kiro steering file so the agent uses and reads the tools correctly.
 
-The server reads the same environment variables as pi and omp and the configuration saved by `/jev-setup`. One server process is one session. The automatic run-end documentation check does not exist in MCP; call `jev_check_diff` with `check: "docs"` instead. `jev_ask` is marked as not read-only while commands are enabled; set `JEV_TOOLS_ALLOW_COMMAND=0` to remove `command` from its schema.
+The server reads the same environment variables as pi and omp and the configuration saved by `/jev-setup`. One server process is one session. MCP has no automatic run-end documentation hook; its absence does not require manual replacement calls. `jev_ask` is marked as not read-only while commands are enabled; set `JEV_TOOLS_ALLOW_COMMAND=0` to remove `command` from its schema.
 
 ### Requirements and compatibility
 
@@ -90,8 +90,8 @@ export JEV_TOOLS_MODEL="openjev"
 
 | Variable | Meaning |
 |---|---|
-| `JEV_TOOLS_URL` | Required complete endpoint URL compatible with the Jev API format. |
-| `JEV_TOOLS_API_KEY` | Required Bearer credential; configuration values are not printed in tool output. |
+| `JEV_TOOLS_URL` | Required complete endpoint URL compatible with the Jev API format. Must be `https:`; plain `http:` is accepted only for `127.0.0.1`, `::1` or `localhost`. |
+| `JEV_TOOLS_API_KEY` | Required Bearer credential; configuration values are not printed in tool output, and command children never receive it. |
 | `JEV_TOOLS_MODEL` | Requested model string, default `openjev`; a moving alias, not a guarantee of served-model identity. |
 | `JEV_TOOLS_MAX_CALLS` | Session-wide non-negative safe-integer call limit; absent or empty means unlimited. Invalid values refuse requests. |
 | `JEV_TOOLS_MAX_USD` | Session-wide finite non-negative cost limit, including fractions; absent or empty means unlimited. Invalid values refuse requests. |
@@ -115,29 +115,37 @@ Without the endpoint or key, tools remain registered and explain the missing con
 
 Use native read/search tools or code for exact source text, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output. Tool reference examples use fictional repository paths and are illustrative calls, not recorded executions.
 
+### Evidence root
+
+All six tools accept optional `root: string`. Without it, the host's current directory or configured MCP server directory retains its existing behavior. An override must name exactly the initial repository's Git top-level or a registered live worktree with the same canonical Git common directory. Relative overrides resolve against the initial directory; absolute paths are accepted only for this parameter. Subdirectories, other clones/repositories, parent traversal and symlink components are refused before evidence collection, command execution, cache access or judgment. There is no fallback to a different checkout.
+
+The admitted root governs files, base/diff, inventories, specification paths, runner plans and command cwd for that call only. It does not change another call or the automatic documentation hook. File arguments remain repository-relative and confined. A command still has ordinary shell permissions, not a sandbox. Check the reported authority, requested/effective root and resolved base before using a result.
+
 ## Read the results
 
-A line without a mark is a **verdict**: a lead to check before editing, deleting or reporting completion, not a proof. Probabilities concern the evidence shown, not everything in your repository.
+Each result begins with execution state: **complete**, **partial**, **not_judged** or **refused**. This describes processing, not correctness, safety or coverage. Items distinguish fresh or cached Jev judgments, static treatment and work never judged. Static selection and conservative fallback carry no invented probability. A judged line without an uncertainty mark is a **verdict**: a lead to check, not proof beyond the supplied evidence.
 
 | Mark | Meaning and next action |
 |---|---|
 | `unsure` | The answer is ambiguous or a control failed. Read the indicated passage or add the specific evidence that would settle it. Do not merely reword the question. |
-| `abstain` | A necessary piece is missing. Add the named file or command evidence and ask once. |
+| `abstain` | A necessary piece is missing. Obtain the named evidence or leave the conclusion open; another Jev call is optional when the changed evidence makes it useful. |
 | `no (not shown)` / `not addressed` | The supplied evidence does not show the statement; that does not make it false. |
 | `uncalibrated` | No established error-rate calibration applies to this ask; treat it as a hint even if its probability is high. |
-| Bracketed lines | Collection, parsing, budget or display limitations, with the next manual action. |
+| Diagnostics and next actions | Typed cause, origin, affected scope, materiality and recovery instructions; distinguish uncertain judgments from work never judged. |
 
 Ordinary boolean verdict bands are at or below 0.20 and at or above 0.80; category/level verdicts require a leading-option probability of at least 0.85 after applicable controls. Fixed checks and navigation tools have their own thresholds, described in their references and [design](docs/design.md).
 
-The footer reports **calls · questions · cost · cache · time**: request count, questions judged, reported USD cost, cache hits/requests and elapsed time. A tool invocation may require several requests for batching or controls. Missing cost reporting is not evidence of a free request.
+Accounting separates **HTTP attempts**, **questions sent**, **requested results** (fresh/cache/static/not judged), **cache probes**, auxiliary controls and passage selection, current reported USD cost and elapsed time. These counts are not interchangeable. A cached judgment can have zero HTTP attempts; zero attempts can also mean static work or no judgment. Unknown cost is unreported, not free. Context values distinguish known, unknown, not collected and not applicable.
+
+pi and omp expose the versioned report as `details.result`. MCP versions from 2025-06-18 expose the same report under `structuredContent.result` with an advertised output schema; older versions receive self-contained text from the same report. Text preserves material limitations, evidence provenance and useful read/runner commands.
 
-In a final report, explicitly identify conclusions marked `unsure` or `abstain` as unconfirmed by Jev. If subsequent reading settles them, distinguish that verification from the tool's result and cite the decisive evidence. Otherwise retain the uncertainty in your summary and recommendation.
+Report current conclusions, decisive evidence with origin and scope, and material reservations. If native reading or execution settles an earlier `unsure` or `abstain` on the same context, attribute the current conclusion to that native evidence, not Jev. If uncertainty returned by Jev remains material, explicitly say Jev did not confirm the conclusion and name the missing evidence and impact. Independent limits, stale evidence and conflicting contexts remain visible. Reported checks are not observed execution; no exhaustive history block or new persistent register is required.
 
 ## Usage guidance for pi and omp
 
 The extension supplies the shared reading guide in both hosts. omp discovers enabled npm plugin rules during normal startup; pi does not automatically discover the package's `rules/` directory. In pi, the same decision policy is part of the `jev_ask` tool guidelines, so it is present whenever `jev_ask` is active. A forced opaque prompt override may bypass this integration; disabled tools or disabled omp rules are not covered. This README block is recommended usage guidance, not itself an installed instruction:
 
-> Before concluding that a failure is a code bug, an incorrect test or an environment problem, or that a plan matches documentation, pass the relevant files to [jev_ask](docs/tools/jev_ask.md) and weigh its answer against your own reading. Include both the failing test and the code it exercises; identify any conclusion that remains unconfirmed.
+> Use Jev for a bounded semantic judgment when it can change an open decision or focus inspection. Use decisive native reading, search or authorized execution directly. A Jev call is not a prerequisite for a conclusion, review or completion. When choosing a call, supply both sides of a comparison and the evidence that distinguishes explanations. Revisit only when changed evidence, context or a useful new question warrants it; repeating unchanged evidence is not a recovery action.
 
 MCP clients receive the guide as server `instructions`, which some clients ignore. Add the [agent instructions](docs/agent-instructions.md) to the project's `CLAUDE.md`, `AGENTS.md` or Kiro steering file.
 
@@ -145,11 +153,11 @@ MCP clients receive the guide as server `instructions`, which some clients ignor
 
 Repository evidence, notes and optional command output are sent to your configured endpoint. Review its data-handling policy before using confidential repositories. See [security guidance](SECURITY.md).
 
-File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions. omp uses execution approval for commands; pi does not supply an additional per-tool command approval; MCP clients apply their own tool approval, and the server marks `jev_ask` as not read-only. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
+File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Files named like secrets (`.env`, `.env.*` except `.env.example`/`.env.sample`/`.env.template`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*`, `secrets*`, any depth, any case) are refused before reading and named with cause `secret_pattern`. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions; they run without `JEV_TOOLS_API_KEY`, and the configured key is replaced with `[redacted]` in their output. omp uses execution approval for commands; pi does not supply an additional per-tool command approval; MCP clients apply their own tool approval, and the server marks `jev_ask` as not read-only. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
 
 ## Automatic documentation check
 
-On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including untracked files. A flagged existing sentence can request one additional turn to update it or explain why it remains correct. Merely unsure sections do not trigger another turn. Missing configuration, disabled automation, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This is not a check for every missing documentation obligation. The MCP server has no run-end hook; there, call `jev_check_diff` with `check: "docs"` before finishing.
+On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including admitted untracked files (not gitignored, not secret-named), which are sent to the endpoint without an explicit tool call. A flagged existing sentence can request one additional turn to inspect and update it or explain with evidence why it remains correct; a flag does not itself establish falsehood or require a second call. Merely unsure sections do not trigger another turn. `JEV_TOOLS_AUTO_DOCS=0`, missing configuration, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This opt-out host feature does not certify documentation completeness. MCP has no hook and requires no manual replacement ritual.
 
 ## Known limits
 

package/SECURITY.md

@@ -16,7 +16,23 @@ This is a solo-maintained project. Reports are reviewed on a best-effort basis;
 
 Report repository-confinement escapes in file evidence collection, including reads outside the selected repository; unintended secret exposure caused by jev-tools; and unintended command execution or bypasses of disabled command execution.
 
-File evidence collection is confined to the repository, but optional commands are not sandboxed: they run with the host's permissions and may read or modify files or access the network. `JEV_TOOLS_ALLOW_COMMAND=0` disables this command path. Selected repository evidence and requested command output are sent to the configured API endpoint; automatic secret redaction is not promised. Review the data and endpoint before use.
+File evidence collection is confined to the repository, but optional commands are not sandboxed: they run with the host's permissions and may read or modify files or access the network. `JEV_TOOLS_ALLOW_COMMAND=0` disables this command path. Selected repository evidence and requested command output are sent to the configured API endpoint. Review the data and endpoint before use.
+
+### Secret-named files are refused
+
+Every evidence admission path (`jev_ask` paths and import closure, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff` diff units and local callers, `jev_select_tests` inventory and the automatic pi/omp documentation check) refuses a file whose base name matches `.env`, `.env.*`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*` or `secrets*`, at any depth and case-insensitively, whatever its Git status (tracked, untracked or added). `.env.example`, `.env.sample` and `.env.template` remain admitted. The refusal happens before the content is read: the result names the path with cause `secret_pattern`, and a question that explicitly requires that file stays unjudged. There is no per-call or environment override. Files with other names are not inspected for secrets.
+
+### Commands never receive the API key
+
+`jev_ask` commands and the Windows PowerShell ACL helper run with the host environment minus `JEV_TOOLS_API_KEY`. Before command output enters a state, every occurrence of the configured key value, whether it came from the environment or the saved configuration, is replaced with `[redacted]` in stdout, stderr and the echoed command line; the result reports how many replacements were made. Detection of other secrets in command output is not promised.
+
+### The key travels only over HTTPS or loopback
+
+`JEV_TOOLS_URL` must use `https:`. Plain `http:` is accepted only for `127.0.0.1`, `::1` or `localhost`; any other `http:` URL is a configuration error, reported without the URL or key and before any request, so the Bearer key is never sent in clear text over a network.
+
+### Automatic documentation check
+
+On pi and omp, the run-end documentation check (disable with `JEV_TOOLS_AUTO_DOCS=0`) sends changed units from a dirty tree to the endpoint without an explicit tool call, including admitted untracked files that are not gitignored. Secret-named files are refused as above; anything else untracked and not ignored can be sent. Keep sensitive scratch files gitignored or outside the repository.
 
 Saved interactive configuration stores the API key in plaintext in a private user-level file (`~/.config/jev-agent-tools/config.json` by default). Privacy uses each operating system's own model: owner-only mode bits on POSIX; on Windows, an access list whose allow entries are only the current user, SYSTEM and Administrators, read by SID through the system Windows PowerShell. Protect the account and back-ups accordingly, or use environment variables from a secret manager instead.
 

package/dist/adapters/ask-files.js

@@ -23,6 +23,7 @@ export async function collectAskFiles(cwd, paths, signal, exec) {
             };
     }
     const skipped = new Set();
+    const secret = new Set();
     const candidates = new Set();
     try {
         let inventory;
@@ -34,7 +35,10 @@ export async function collectAskFiles(cwd, paths, signal, exec) {
         const add = async (path) => {
             const admission = await checkFileAdmission(cwd, path, exec, signal, 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)))
@@ -181,7 +185,12 @@ export async function collectAskFiles(cwd, paths, signal, exec) {
                 };
             }
         }
-        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/dist/adapters/ask-proof.js

@@ -1,6 +1,6 @@
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.js";
-import { collectFiles } from "./files.js";
+import { checkFileAdmission, collectFiles } from "./files.js";
 import { verifyGitUtf8 } from "./utf8.js";
 export async function collectAskRepository(exec, cwd, base, signal) {
     try {
@@ -37,20 +37,25 @@ export async function collectAskRepository(exec, cwd, base, signal) {
             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();
         const beforeReads = new Map();
         return {
             ok: true,
             root,
             known,
+            beforeKnown,
             baseSha,
             read(path) {
                 let pending = reads.get(path);
@@ -78,9 +83,50 @@ export async function collectAskRepository(exec, cwd, base, signal) {
                 let pending = beforeReads.get(path);
                 if (!pending) {
                     pending = (async () => {
-                        if (!baseSha || !beforeKnown.has(path))
-                            return { ok: true, text: null };
                         try {
+                            if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+                                return {
+                                    ok: false,
+                                    cause: "forbidden_path",
+                                    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,
+                                    cause: "git_failure",
+                                    error: `${path}: historical admission unavailable`,
+                                };
+                            if (ignoredPath.code === 0)
+                                return {
+                                    ok: false,
+                                    cause: "ignored_path",
+                                    error: `${path}: gitignored: not sent to Jev`,
+                                };
+                            if (!baseSha)
+                                return {
+                                    ok: false,
+                                    error: `${path}: comparison base unavailable`,
+                                };
+                            if (!beforeKnown.has(path))
+                                return known.has(path)
+                                    ? { ok: true, text: null }
+                                    : {
+                                        ok: false,
+                                        error: `${path}: not in current or comparison base inventory`,
+                                    };
+                            const entry = beforeEntries.get(path) ?? "";
+                            if (!/^(?:100644|100755) blob /.test(entry))
+                                return {
+                                    ok: false,
+                                    cause: entry.startsWith("120000 ")
+                                        ? "symlink"
+                                        : "file_unavailable",
+                                    error: `${path}: not a regular file at comparison base: not sent to Jev`,
+                                };
                             const object = await exec("git", [
                                 "rev-parse",
                                 "--verify",
@@ -117,10 +163,20 @@ export async function collectAskRepository(exec, cwd, base, signal) {
                                     ok: false,
                                     error: `before evidence unavailable for ${path}`,
                                 };
+                            if (loaded.stdout.includes("\0"))
+                                return {
+                                    ok: false,
+                                    cause: "binary_or_non_utf8",
+                                    error: `${path}: binary content: not sent to Jev`,
+                                };
                             const decoded = verifyGitUtf8(loaded.stdout, id, size);
                             return decoded.ok
                                 ? decoded
-                                : { ok: false, error: `${path}: ${decoded.error}` };
+                                : {
+                                    ok: false,
+                                    cause: "binary_or_non_utf8",
+                                    error: `${path}: ${decoded.error}`,
+                                };
                         }
                         catch (error) {
                             return { ok: false, error: String(error) };

package/dist/adapters/command.js

@@ -5,8 +5,39 @@ import { ASK_TIMEOUT_S, OUTPUT_CHUNK_CHARS, OUTPUT_FAILURE_WINDOW_LINES, OUTPUT_
 import { cleanOutput, createRarityCompressor, failureTargets, lineShape, } from "../core/command-output.js";
 import { outputLines } from "./output-lines.js";
 import { resolveShell } from "./shell.js";
-export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_S, signal) {
+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, secret) {
+    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, cwd, command, timeoutS = ASK_TIMEOUT_S, signal, 
+/** Configured Jev API key, replaced in the captured command and output. */
+secret) {
     const directory = await mkdtemp(join(tmpdir(), "jev-output-"));
+    let commandExecution = "not_started";
+    let completion;
     try {
         await chmod(directory, 0o700);
         const stdoutPath = join(directory, "stdout");
@@ -17,7 +48,13 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
             const shell = resolveShell();
             // Fail closed: never spawn a bare name that PATH could resolve to WSL.
             if (!shell.ok)
-                throw new Error(shell.error);
+                return {
+                    ok: false,
+                    cause: "file_unavailable",
+                    commandExecution: "not_started",
+                    error: shell.error,
+                };
+            commandExecution = "unknown";
             executed = await exec(shell.executable, [
                 ...shell.prefix,
                 "-c",
@@ -26,27 +63,19 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
                 stdoutPath,
                 stderrPath,
             ], { 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();
@@ -65,6 +94,9 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
         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 = [];
@@ -74,17 +106,23 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
         let lineOmittedChars = 0;
         let shapeLimitExceeded = false;
         const texts = [];
+        let redactions = 0;
+        const redacted = (text) => {
+            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();
             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) &&
                     frequencies.size >= OUTPUT_SHAPE_MAX_COUNT) {
@@ -122,17 +160,19 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
                 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;
@@ -142,11 +182,11 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
                     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();
@@ -157,8 +197,10 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
         }
         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] ?? "",
@@ -173,6 +215,17 @@ export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_
             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 {

package/dist/adapters/docs.js

@@ -12,6 +12,7 @@ export async function collectDocsInventory(exec, cwd, signal) {
     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();
@@ -23,6 +24,7 @@ export async function collectDocsInventory(exec, cwd, signal) {
     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));
@@ -46,7 +48,11 @@ export async function collectDocsInventory(exec, cwd, signal) {
                     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;
@@ -130,10 +136,17 @@ export function docsDeclarationSearch(exec, inventory, signal) {
                     if (path === undefined)
                         return;
                     const location = await resolveInsideRepo(inventory.cwd, path);
-                    const admitted = location.ok &&
-                        (await checkFileAdmission(inventory.cwd, location.rel, exec, signal, inventory.tracked)).ok;
-                    if (admitted)
+                    const admission = location.ok
+                        ? await checkFileAdmission(inventory.cwd, location.rel, exec, signal, inventory.tracked)
+                        : location;
+                    if (admission.ok)
                         paths.push(path);
+                    else if (admission.cause === "secret_pattern")
+                        inventory.limits.push({
+                            path,
+                            reason: admission.error,
+                            cause: admission.cause,
+                        });
                 }
             }));
             return paths;
@@ -142,12 +155,19 @@ export function docsDeclarationSearch(exec, inventory, signal) {
         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;
+        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",