jev-agent-tools 0.1.3

package/docs/tools/jev_check_diff.md

@@ -0,0 +1,77 @@
+# jev_check_diff
+
+Review a finished diff for risk, stale existing documentation or specification drift using fixed questions.
+
+## Use for
+
+Review completed changes before committing or reporting completion, review a branch against a Git ref, or check whether existing documentation remains true after source changes.
+
+## Use another tool when
+
+Use native `git diff` execution to read the diff, [jev_select_tests](jev_select_tests.md) to choose existing tests, and [jev_ask](jev_ask.md) for your own typed judgment. Do not review a half-written change as if it were complete.
+
+## Evidence model
+
+Changed declarations, slices, files or hunks become before/after evidence units. Tests are supporting evidence, never units to judge. Preset questions are fixed in code; the caller chooses a check, not raw questions. Jev does not run the code. Verbatim specification text is evidence, not instructions.
+
+## Parameters
+
+| Field | Type / default | Meaning |
+|---|---|---|
+| `check` | Required `"risk"`, `"docs"` or `"spec"` | Select the preset below. |
+| `base` | Optional nonempty Git ref, default `HEAD` | Compare the current tree, including untracked files, with this revision. |
+| `spec_path` | Optional nonempty repository-relative string | Required for `spec`: Markdown specification with `### REQ-…` headings. |
+| `witnesses` | Optional `"off"`, `"auto"` (default), `"on"` | Control decoy/reference evidence in the built-in risk matrix. |
+| `dimensions` | Optional map of names to nonempty statements | Additional risk rules: positive statements true of a risky change. Built-in names are reserved. Marked uncalibrated, without severity or witnesses. |
+| `only` | Optional nonempty array of distinct nonempty names | Restrict risk to named built-in or custom dimensions; custom names must be supplied in `dimensions`. |
+| `max_calls` | Optional non-negative integer | Bound all requests, including local-caller checks, controls and severity; unjudged work remains unchecked. |
+
+Custom dimensions and `only` apply to risk and are ignored by docs/spec. Unknown fields, invalid risk dimensions or unresolved refs are rejected with guidance. File paths follow repository confinement.
+
+### risk
+
+Ask built-in correctness, security, compatibility and reliability questions, then grade flagged risks by severity. Optional witnesses check the setup with decoy and known-positive evidence. Failed witnesses make findings unsure with raw values and a reason.
+
+For replaced member accesses, separate local-caller checks inspect statically resolved tracked callers, including import aliases, and their imported providers. They account for coordinated caller/provider edits. Literal-name discovery cannot cover dynamic access that never names the target. Unknown providers, partial units and metaprogramming remain visibly unchecked. Local checks run once per eligible unit, not once per caller; local evidence limits do not invalidate the separate risk matrix.
+
+### docs
+
+Judge up to 40 existing tracked Markdown sections mentioning changed code or importing source, and identify the existing sentence made false. Collection and traversal limits are visible. This is not an exhaustive detector of missing documentation, arbitrary companion edits or every stale sentence.
+
+### spec
+
+Judge requirements under `### REQ-…` headings against changed behavior and identify behavior absent from the specification. `spec_path` is required and read inside the repository. Markdown tables produce an explicit interpretation limit; an arbitrary document without requirement headings is not treated as a complete specification.
+
+## Example
+
+Illustrative call with a fictional repository convention, not a recorded execution:
+
+```json
+{
+  "check": "risk",
+  "base": "HEAD",
+  "witnesses": "auto",
+  "dimensions": {
+    "rounding": "The change rounds a monetary amount before the final conversion to cents"
+  },
+  "max_calls": 12
+}
+```
+
+For another preset, use `{"check":"docs","base":"HEAD"}` or `{"check":"spec","base":"HEAD","spec_path":"docs/requirements.md"}`; these are also illustrative calls, not recorded executions.
+
+## Results and next action
+
+Findings name the evidence unit, stale sentence or requirement and its probability. Fixed findings require at least 0.7. Docs probabilities from 0.2 up to 0.7 are unsure without an additional judgment; read the indicated wording. Local-caller probabilities between 0.2 and 0.7 are unsure; `cannot_tell` at least 0.3 is abstain naming the missing provider or binding. Failed witness batches remain unsure. Read flagged source, callers or documentation before editing and preserve unresolved uncertainty in reports. See [shared result reading](../../README.md#read-the-results).
+
+## Limits and failure behavior
+
+No findings is not proof of safety, unseen-caller coverage or complete documentation. Unjudged units, callers, sections, requirements and severity are named when request or session budgets stop work. Parser gaps and unresolved dynamic providers remain limits, not invented answers. Missing configuration refuses judgment without a chat-model fallback. Static collection is bounded and does not evaluate third-party code.
+
+## Host differences
+
+Explicit checks share the same read-only contract in pi and omp. The extension also runs only the docs preset automatically at eligible run end; see [automatic documentation checking](../../README.md#automatic-documentation-check). Risk and spec never run automatically.
+
+## Related tools
+
+[Typed situation judgment](jev_ask.md), [existing test selection](jev_select_tests.md), [design policy](../design.md).

package/docs/tools/jev_find_files.md

@@ -0,0 +1,59 @@
+# jev_find_files
+
+Rank repository files for a behavioral goal and suggest the entry point to read first.
+
+## Use for
+
+Start a task in unfamiliar code when you can describe the behavior but do not know its filename or exact identifier.
+
+## Use another tool when
+
+Use native filename search for known names and text search for known strings, regular expressions or symbols. Use [jev_ask_files](jev_ask_files.md) to ask questions about candidates you already have, or [jev_locate_in_file](jev_locate_in_file.md) to locate a range inside one known large file.
+
+## Evidence model
+
+Deterministic lexical pre-ranking and name judgments produce candidates; the tool then reads bounded keyword-selected passages and narrows a shortlist for the entry-point choice. Jev sees excerpts, not every complete file. Names help ranking but do not establish behavior. A behavioral sentence is more useful than a guessed identifier; known identifiers belong in `keywords`. The ranked list estimates whether each file helps with the goal, not whether it implements the complete behavior.
+
+## Parameters
+
+| Field | Type / default | Meaning |
+|---|---|---|
+| `goal` | Required nonempty string | Behavioral sentence with at least five content words for an unqualified entry verdict. Shorter goals are accepted but capped at unsure. |
+| `keywords` | Optional array of nonempty strings, default empty | Known identifiers or terms steering lexical ranking and excerpt selection. |
+| `scope` | Optional directory string or array of directory strings, default repository | Restrict search; an incorrect scope may yield none. |
+| `exclude` | Optional array of glob strings | Skip matches; excluding tests also removes their context from results. |
+| `effort` | Optional `"quick"`, `"default"` (default), or `"thorough"` | Bound breadth: quick ranks up to 32 name candidates and reads 8; default 128 and 20; thorough 256 and 40. Wider search is not a guarantee of a better entry. |
+| `max_calls` | Optional non-negative integer | Bound requests including controls; return the best-ranked work completed so far and state omissions. |
+
+Unknown fields or invalid values are rejected. All paths are repository-relative; absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not allowed file inputs.
+
+## Example
+
+Illustrative call with fictional repository paths, not a recorded execution:
+
+```json
+{
+  "goal": "Find where invoice amounts are rounded before storage",
+  "keywords": ["invoice", "round"],
+  "scope": ["src"],
+  "exclude": ["**/generated/**"],
+  "effort": "quick",
+  "max_calls": 6
+}
+```
+
+## Results and next action
+
+`entry:` names the file to open first with its probability, followed by ranked related paths and a suggested read. `entry: unsure` can mean two plausible entries, order sensitivity, inconclusive excerpts or a short goal: read the leading two candidates. `entry: none` means no candidate fit the supplied evidence: rephrase the behavioral goal or widen scope. Paths and probabilities are not source text; read the files before editing. See [shared result reading](../../README.md#read-the-results).
+
+## Limits and failure behavior
+
+Candidate counts and excerpts are bounded; excluded, unreadable or oversized evidence and exhausted budgets leave explicit limits. Keyword pre-ranking and name guards do not prove that omitted files are irrelevant. Missing configuration refuses judgment without a chat-model fallback. Optional native search acceleration may fall back to the available collection path; this does not broaden the evidence guarantee. Session budgets remain separate from `max_calls`.
+
+## Host differences
+
+pi exposes this semantic tool alongside its native filename `find`. In omp it starts inactive when native semantic `find` is active; when native `find` is absent, session startup activates `jev_find_files`. omp filename search is `glob`. Judgment behavior is otherwise shared and read-only.
+
+## Related tools
+
+[Per-file triage](jev_ask_files.md), [large-file location](jev_locate_in_file.md), [design policy](../design.md).

package/docs/tools/jev_locate_in_file.md

@@ -0,0 +1,51 @@
+# jev_locate_in_file
+
+Choose the line range in one large file that serves a behavioral goal, then read that range directly.
+
+## Use for
+
+A known file is too large to read whole and you need the part serving a particular goal, such as retry scheduling or flag parsing. Prefer goal-based location to opening arbitrary successive chunks.
+
+## Use another tool when
+
+Use native text search for known symbols or strings, direct reading for files smaller than 19 KB, [jev_find_files](jev_find_files.md) for unknown filenames, and [jev_ask_files](jev_ask_files.md) for independent questions about multiple files.
+
+## Evidence model
+
+Code splits the file into declarations or sections and constructs a choice over relevant ranges. Larger files use streamed window outlines and refinement, with explicit limitations. Jev reads supplied source, not runtime behavior. Several sections can legitimately share a goal, dividing probability between them; two plausible ranges do not imply that either is wrong. Optional parser failures use heuristic sections and report the gap.
+
+## Parameters
+
+| Field | Type / default | Meaning |
+|---|---|---|
+| `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. |
+
+There is no per-invocation `max_calls` parameter; session budgets still apply. Unknown fields are rejected. Absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs.
+
+## Example
+
+Illustrative call with a fictional repository path, not a recorded execution:
+
+```json
+{
+  "path": "src/scheduler.ts",
+  "goal": "Find the section that reschedules tasks after a transient failure"
+}
+```
+
+## Results and next action
+
+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).
+
+## 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.
+
+## 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.
+
+## Related tools
+
+[Semantic file finding](jev_find_files.md), [per-file triage](jev_ask_files.md), [design policy](../design.md).

package/docs/tools/jev_select_tests.md

@@ -0,0 +1,59 @@
+# jev_select_tests
+
+Select affected existing tests from a diff and return runner commands without running or collecting tests.
+
+## Use for
+
+After editing code, decide which existing scenarios to execute while preserving conservative fallbacks and runner context.
+
+## Use another tool when
+
+Use native reading/search to inspect exact test names and shell execution to run them. Use [jev_check_diff](jev_check_diff.md) for risk or documentation review, and [jev_ask](jev_ask.md) for one test-versus-implementation judgment. This tool does not decide whether a new test scenario must be written.
+
+## Evidence model
+
+Static discovery reads tracked tests, literal project configuration and imports without evaluating third-party configuration or invoking collection. Import closure includes unchanged intermediates and applicable pytest `conftest` fixtures. Touched tests are selected without judgment. Remaining scenarios receive changed-unit pointers, using test and import evidence. Runtime and type tests remain separate; commands preserve working directory, config, project, framework and project options.
+
+Residual exported-unit checks concern changed units not exercised by any discovered test, only within the discovered inventory. They are not global coverage reports or obligations to add a scenario. Unsupported or unresolved runners keep that conclusion unsure and name a manual next action.
+
+## Parameters
+
+| Field | Type / default | Meaning |
+|---|---|---|
+| `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. |
+| `max_calls` | Optional non-negative integer | Bound requests; unjudged scenarios remain selected. Separate from session budgets. |
+
+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.
+
+## Example
+
+Illustrative call with fictional repository paths, not a recorded execution:
+
+```json
+{
+  "base": "HEAD",
+  "paths": ["test/**/*.test.ts"],
+  "witnesses": "auto",
+  "max_calls": 8
+}
+```
+
+## Results and next action
+
+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).
+
+## Limits and failure behavior
+
+No tests are executed or collected. Discovery is static and runner/version support is bounded; calculated config, unresolved runners, dynamic names and missing optional parsers can prevent precise filtering. Unavailable Jev or exhausted budgets preserve tests rather than silently dropping them. Whole-file fallbacks avoid unsafe name filtering but do not prove the discovery inventory complete. Residual coverage witnesses check setup, not execution. This tool cannot infer required new scenarios or replace actual verification.
+
+## Host differences
+
+Both hosts share static discovery and command planning; omp marks this tool read-only. Host-native tools perform execution separately. Optional parser availability changes evidence precision and is reported, not concealed behind a host-specific judgment implementation.
+
+## Related tools
+
+[Diff review](jev_check_diff.md), [combined judgment](jev_ask.md), [design policy](../design.md).

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "jev-agent-tools",
+  "version": "0.1.3",
+  "type": "module",
+  "license": "MIT",
+  "description": "Six evidence-oriented tools for pi and omp coding agents, compatible with the Jev API format.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NomenAK/jev-tools.git"
+  },
+  "homepage": "https://github.com/NomenAK/jev-tools#readme",
+  "bugs": {
+    "url": "https://github.com/NomenAK/jev-tools/issues"
+  },
+  "keywords": [
+    "typescript",
+    "coding-agents",
+    "code-review",
+    "test-selection",
+    "pi",
+    "omp",
+    "jev"
+  ],
+  "files": [
+    "src/",
+    "rules/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/design.md",
+    "docs/tools/jev_ask.md",
+    "docs/tools/jev_ask_files.md",
+    "docs/tools/jev_find_files.md",
+    "docs/tools/jev_locate_in_file.md",
+    "docs/tools/jev_check_diff.md",
+    "docs/tools/jev_select_tests.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "check:imports": "node scripts/check-imports.ts",
+    "lint": "biome check src test scripts",
+    "test": "node --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.87.1"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@types/node": "^24.0.0",
+    "jest": "30.5.2",
+    "typescript": "^5.9.0",
+    "vitest": "~3.2.7"
+  },
+  "optionalDependencies": {
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/napi": "^0.45.3",
+    "@ff-labs/fff-node": "^0.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/rules/jev-ask.md

@@ -0,0 +1,4 @@
+---
+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

package/src/adapters/analysis-context.ts

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import type { SgNode } from "@ast-grep/napi";
+import {
+  type LexicalSource,
+  type LexicalToken,
+  tokenize,
+} from "../core/lexical.ts";
+import type { SyntaxRootParser } from "../core/syntax.ts";
+import type { Result } from "../result.ts";
+import { loadSyntaxRootParser } from "./syntax.ts";
+
+export interface AnalysisCounter {
+  parsed(path: string, fingerprint: string): void;
+  tokenized(path: string, fingerprint: string): void;
+  resolved(path: string, fingerprint: string): void;
+}
+export interface AnalysisContext extends LexicalSource {
+  parser: SyntaxRootParser | undefined;
+  fingerprint(text: string): string;
+  counter: AnalysisCounter | undefined;
+}
+
+/** Owns one invocation's source versions; never retains repository data across calls. */
+export async function createAnalysisContext(
+  counter?: AnalysisCounter,
+  sourceParser?: SyntaxRootParser,
+): Promise<AnalysisContext> {
+  const fingerprints = new Map<string, string>();
+  const fingerprint = (text: string): string => {
+    let value = fingerprints.get(text);
+    if (value === undefined) {
+      value = createHash("sha256").update(text).digest("hex");
+      fingerprints.set(text, value);
+    }
+    return value;
+  };
+  const lexical = new Map<string, Map<string, LexicalToken[]>>();
+  const tokenizeSource: LexicalSource["tokenize"] = (
+    path,
+    text,
+    python = false,
+  ) => {
+    const version = fingerprint(text);
+    let versions = lexical.get(path);
+    if (!versions) {
+      versions = new Map();
+      lexical.set(path, versions);
+    }
+    const key = `${version}:${python}`;
+    let tokens = versions.get(key);
+    if (!tokens) {
+      counter?.tokenized(path, version);
+      tokens = tokenize(text, python);
+      versions.set(key, tokens);
+    }
+    return tokens;
+  };
+  const source = sourceParser ?? (await loadSyntaxRootParser());
+  if (!source)
+    return {
+      parser: undefined,
+      fingerprint,
+      counter,
+      tokenize: tokenizeSource,
+    };
+  const roots = new Map<string, Map<string, Result<{ root: SgNode }>>>();
+  const parser: SyntaxRootParser = {
+    supports: source.supports,
+    parseRaw(path, text) {
+      const version = fingerprint(text);
+      let versions = roots.get(path);
+      if (!versions) {
+        versions = new Map();
+        roots.set(path, versions);
+      }
+      let parsed = versions.get(version);
+      if (!parsed) {
+        counter?.parsed(path, version);
+        parsed = source.parseRaw(path, text);
+        versions.set(version, parsed);
+      }
+      return parsed;
+    },
+    parse(path, text) {
+      const parsed = this.parseRaw(path, text);
+      if (!parsed.ok) return parsed;
+      return parsed.root.find({ rule: { kind: "ERROR" } })
+        ? { ok: false, error: "Source syntax incomplete" }
+        : parsed;
+    },
+    declarations: source.declarations,
+  };
+  return {
+    parser,
+    fingerprint,
+    counter,
+    tokenize: tokenizeSource,
+    resolved: (path, text) => counter?.resolved(path, fingerprint(text)),
+  };
+}

package/src/adapters/ask-files.ts

@@ -0,0 +1,236 @@
+import { readdir, stat } from "node:fs/promises";
+import { dirname, isAbsolute, matchesGlob, relative, resolve } from "node:path";
+import { CONCURRENCY, MAX_FILES, TIMEOUT_MS } from "../constants.ts";
+import type { GitExec } from "../core/git.ts";
+import type { FileIdentity } from "../core/integrity.ts";
+import type { Result } from "../result.ts";
+import {
+  checkFileAdmission,
+  collectFiles,
+  resolveInsideRepo,
+} from "./files.ts";
+
+const excludedDirectories = new Set(["node_modules", ".git", "dist", "build"]);
+const lockfile =
+  /(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|Gemfile\.lock|poetry\.lock|uv\.lock|composer\.lock|Pipfile\.lock|go\.sum)$/;
+export interface AskFile {
+  path: string;
+  content: string;
+  identity: FileIdentity;
+}
+export async function collectAskFiles(
+  cwd: string,
+  paths: readonly string[],
+  signal?: AbortSignal,
+  exec?: GitExec,
+): Promise<Result<{ files: AskFile[]; skipped: string[] }>> {
+  if (!paths.length)
+    return {
+      ok: false,
+      error: "Provide at least one path, directory or glob.",
+    };
+  for (const path of paths) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
+      return {
+        ok: false,
+        error: `Internal URLs are not files; use read for ${path}.`,
+      };
+    if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+      return {
+        ok: false,
+        error: `Path must remain inside the repository: ${path}.`,
+      };
+  }
+  const skipped = new Set<string>();
+  const candidates = new Set<string>();
+  try {
+    let inventory: Set<string> | undefined;
+    if (exec) {
+      const result = await exec(
+        "git",
+        ["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+        { cwd, timeout: TIMEOUT_MS, signal },
+      );
+      if (result.code === 0)
+        inventory = new Set(result.stdout.split("\0").filter(Boolean));
+    }
+    const add = async (path: string) => {
+      const admission = await checkFileAdmission(
+        cwd,
+        path,
+        exec,
+        signal,
+        inventory,
+      );
+      if (!admission.ok) {
+        skipped.add(`${path} (${admission.error})`);
+        return;
+      }
+      if (path.split("/").some((part) => excludedDirectories.has(part)))
+        skipped.add(`${path} (build output or dependencies)`);
+      else if (lockfile.test(path)) skipped.add(`${path} (lockfile)`);
+      else candidates.add(path);
+    };
+    const walk = async (directory: string, pattern?: string): Promise<void> => {
+      signal?.throwIfAborted();
+      const safe = await resolveInsideRepo(cwd, directory);
+      if (!safe.ok) {
+        skipped.add(`${directory} (${safe.error})`);
+        return;
+      }
+      const entries = await readdir(safe.abs, { withFileTypes: true });
+      await Promise.all(
+        entries.map(async (entry) => {
+          const path = relative(
+            cwd,
+            resolve(cwd, directory, entry.name),
+          ).replaceAll("\\", "/");
+          if (entry.isSymbolicLink()) {
+            skipped.add(`${path} (symbolic link)`);
+            return;
+          }
+          if (entry.isDirectory()) {
+            if (excludedDirectories.has(entry.name)) {
+              skipped.add(`${path}/ (build output or dependencies)`);
+              return;
+            }
+            await walk(path, pattern);
+            return;
+          }
+          if (
+            entry.isFile() &&
+            (!pattern ||
+              matchesGlob(
+                path
+                  .split("/")
+                  .map((part) =>
+                    part.startsWith(".") ? `__dot__${part.slice(1)}` : part,
+                  )
+                  .join("/"),
+                pattern
+                  .split("/")
+                  .map((part) =>
+                    part.startsWith(".") ? `__dot__${part.slice(1)}` : part,
+                  )
+                  .join("/"),
+              ))
+          )
+            await add(path);
+        }),
+      );
+    };
+    for (const input of paths) {
+      signal?.throwIfAborted();
+      const safe = await resolveInsideRepo(cwd, input);
+      const info = safe.ok
+        ? await stat(safe.abs).catch(() => undefined)
+        : undefined;
+      if (info && safe.ok) {
+        if (info.isFile()) {
+          const admission = await checkFileAdmission(
+            cwd,
+            safe.rel,
+            exec,
+            signal,
+            inventory,
+          );
+          if (!admission.ok) return admission;
+        }
+        if (input.split("/").some((part) => excludedDirectories.has(part))) {
+          skipped.add(`${input} (build output or dependencies)`);
+          continue;
+        }
+        if (info.isDirectory()) await walk(safe.rel || ".");
+        else if (info.isFile()) {
+          const admission = await checkFileAdmission(
+            cwd,
+            safe.rel,
+            exec,
+            signal,
+            inventory,
+          );
+          if (!admission.ok) return admission;
+          await add(safe.rel);
+        } else skipped.add(`${input} (not a regular file)`);
+      } else {
+        const parts = input.split("/");
+        const wildcard = parts.findIndex((part) => /[?*[\]{}]/.test(part));
+        if (wildcard < 0) {
+          if (!safe.ok && !safe.error.includes("ENOENT")) return safe;
+          skipped.add(`${input} (missing)`);
+          continue;
+        }
+        const prefix = parts.slice(0, wildcard).join("/") || ".";
+        const prefixLocation = await resolveInsideRepo(cwd, prefix);
+        if (!prefixLocation.ok) return prefixLocation;
+        const pattern = input.replace(/^\.\//, "");
+        if (inventory) {
+          for (const path of inventory) {
+            const dotPath = path
+              .split("/")
+              .map((part) =>
+                part.startsWith(".") ? `__dot__${part.slice(1)}` : part,
+              )
+              .join("/");
+            const dotPattern = pattern
+              .split("/")
+              .map((part) =>
+                part.startsWith(".") ? `__dot__${part.slice(1)}` : part,
+              )
+              .join("/");
+            if (matchesGlob(dotPath, dotPattern)) await add(path);
+          }
+        } else await walk(prefix, pattern);
+      }
+    }
+    const files: AskFile[] = [];
+    const sorted = [...candidates].sort();
+    const contributions = new Map<string, number>();
+    for (const path of sorted) {
+      const directory = dirname(path);
+      contributions.set(directory, (contributions.get(directory) ?? 0) + 1);
+    }
+    let accepted = 0;
+    for (let i = 0; i < sorted.length; i += CONCURRENCY) {
+      const rows = await Promise.all(
+        sorted.slice(i, i + CONCURRENCY).map(async (path) => {
+          const result = await collectFiles(cwd, [path], signal, {
+            exec,
+            inventory,
+          });
+          if (!result.ok) {
+            skipped.add(`${path} (${result.error})`);
+            return;
+          }
+          const identity = result.identities[0];
+          if (!identity) return;
+          if (
+            identity.content.includes("\0") ||
+            identity.readSha256 !== identity.insertedSha256
+          ) {
+            skipped.add(`${path} (binary or invalid UTF-8)`);
+            return;
+          }
+          return { path, content: identity.content, identity };
+        }),
+      );
+      for (const file of rows)
+        if (file) {
+          accepted++;
+          if (files.length < MAX_FILES) files.push(file);
+        }
+      if (accepted > MAX_FILES) {
+        const largest = [...contributions]
+          .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+          .slice(0, 5);
+        return {
+          ok: false,
+          error: `At least ${accepted} files exceeds MAX_FILES=${MAX_FILES}; narrow paths. Largest expanded directories: ${largest.map(([path, count]) => `${path}: ${count}`).join(", ")}.`,
+        };
+      }
+    }
+    return { ok: true, files, skipped: [...skipped].sort() };
+  } catch (error) {
+    return { ok: false, error: `Cannot expand paths: ${String(error)}` };
+  }
+}