@selesai/code 0.13.37 → 0.13.39

package/dist/extensions/jev-ask-tool.ts

@@ -15,7 +15,7 @@
  */
 import { execFile } from "node:child_process";
 import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
-import { basename, isAbsolute, normalize, relative, resolve } from "node:path";
+import { basename, isAbsolute, normalize, relative, resolve, sep } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	createLocalBashOperations,
@@ -36,7 +36,10 @@ import {
 	UNTRUSTED_MATERIAL_FOCUS,
 	warnJevUnavailableOnce,
 	type JevAbstainReason,
+	type JevAnswers,
+	type JevFailureDiagnostic,
 } from "./jev/decisions.ts";
+import { isScriptPath, keywordWindows, loadTypeScript, type SourceUnit, splitSourceUnits } from "./jev-find-source.ts";
 
 /** The tool's registered name. */
 export const ASK_JEV_TOOL = "ask_jev";
@@ -342,29 +345,68 @@ export function renderAskAnswers(input: {
 }
 
 // ---------------------------------------------------------------------------
-// jev_find: ripgrep gathers candidates, Jev judges each one
+// jev_find: ripgrep gathers files; Jev narrows directories, then files, then source units
 // ---------------------------------------------------------------------------
 
 /** The file finder's registered name. */
 export const JEV_FIND_TOOL = "jev_find";
 /** ponytail: 16 nouls per request (the JevPDF batch size); raise once Jev is measured on larger blocks. */
 export const FIND_BATCH = 16;
-/** Three batches, sent in parallel, so a find costs one Jev round trip. */
-export const MAX_FIND_CANDIDATES = 48;
+/** ponytail: a set this small (three parallel batches) is judged file by file, without directory descent. */
+export const FIND_DIRECT_FILES = 48;
+/** ponytail: at most 128 files judged per call (eight batches), best word/path score first. */
+export const FIND_MAX_JUDGED_FILES = 128;
+/** ponytail: hard cap of 12 Jev requests per call, retries included; raise once latency and cost are measured. */
+export const FIND_MAX_REQUESTS = 12;
+/** ponytail: directory descent spends at most 4 of those requests (64 directory questions over all levels). */
+export const FIND_DIR_REQUESTS = 4;
+/** ponytail: 2 requests are held back for the source-unit stage (32 units). */
+export const FIND_UNIT_REQUESTS = 2;
+/** ponytail: about 16 KB of verbatim source per call; the rest stays reachable through the reading leads. */
+export const FIND_MAX_SOURCE_BYTES = 16 * 1024;
+/** ponytail: descend at most 4 directory levels below the search root. */
+export const FIND_MAX_DEPTH = 4;
+/** ponytail: keep a directory at 0.35 or above: pruning drops every file under it, so it errs toward keeping. */
+export const FIND_DIR_KEEP = 0.35;
+/** ponytail: at most 6 candidate units per relevant file, each shown as at most 60 lines. */
+export const FIND_UNITS_PER_FILE = 6;
+export const FIND_UNIT_MAX_LINES = 60;
+const FIND_DIR_FILE_NAMES = 15;
+const FIND_DIR_HIT_LINES = 3;
 const FIND_MATCH_LINES = 6;
 const FIND_DEFAULT_LIMIT = 8;
 const FIND_MIN_RELEVANCE = 0.5;
-/** Room each batch keeps for the questions and JSON scaffolding. */
+/** Files that still get keyword-window source when Jev could not rank them. */
+const FIND_FALLBACK_SOURCE_FILES = 3;
+/** The asker's question is clipped to this before it is repeated in every request. */
+const FIND_REQUEST_BYTES = 2 * 1024;
+/** Room each file batch keeps for the questions and JSON scaffolding when sizing snippets. */
 const FIND_QUESTION_RESERVE = 6 * 1024;
+/** Lines of a long unit shown above its best keyword line. */
+const FIND_FOCUS_LEAD = 10;
+
+/** One file ripgrep offered. */
+export interface FindFile {
+	path: string;
+	/** Matched line numbers (pattern mode). */
+	lines: number[];
+	/** Matched lines as `L12: text` (pattern mode). */
+	hits: string[];
+	/** Question words in the path, plus matched lines (pattern mode) or question words in the content. */
+	score: number;
+}
 
 export interface FindCandidate {
 	path: string;
-	/** Matched line numbers (pattern mode only). */
+	/** Matched line numbers, or the best keyword lines, best first. */
 	lines: number[];
-	/** What Jev reads: the matched lines, or the head of the file. */
+	/** What Jev reads: the matched lines, or the file's best keyword lines, or its head. */
 	snippet: string;
 }
 
+/** Sends one decisions request. The tool binds it to `askJevAnswers`; tests pass a fake. */
+export type JevFindAsk = (payload: Record<string, unknown>) => Promise<JevAnswers>;
+
 /** Run ripgrep with an argument list (no shell). Exit 1 is "no matches"; an overfull buffer keeps what arrived. */
 function runRg(bin: string, args: string[], cwd: string, signal: AbortSignal | undefined): Promise<string> {
 	return new Promise((done, fail) => {
@@ -414,7 +456,7 @@ export function excerpt(text: string, words: readonly string[], maxBytes: number
 	if (best.length === 0) return { lines: [], snippet: clip(text, maxBytes).text };
 	const inOrder = [...best].sort((a, b) => a.index - b.index);
 	const snippet = inOrder.map((hit) => `L${hit.index + 1}: ${rows[hit.index].trim().slice(0, 240)}`).join("\n");
-	// Pointers lead with the best-matching lines.
+	// Leads start at the best-matching lines.
 	return { lines: best.map((hit) => hit.index + 1), snippet: clip(snippet, maxBytes).text };
 }
 
@@ -424,22 +466,32 @@ function pathOverlap(path: string, words: readonly string[]): number {
 	return parts.filter((part) => words.some((word) => word.includes(part) || part.includes(word))).length;
 }
 
+const byScore = (a: FindFile, b: FindFile) => b.score - a.score || a.path.localeCompare(b.path);
+
+export interface FindGatherOptions {
+	rg: string;
+	cwd: string;
+	/** Search root relative to `cwd`; "." for the working directory. */
+	root: string;
+	question: string;
+	pattern?: string;
+	glob?: string;
+	ignoreCase?: boolean;
+}
+
 /**
- * Candidate files under `root`, most promising first. With `pattern`, the files ripgrep matches
- * (most matches first) with their matched lines as the snippet; without it, every file ripgrep
- * lists (question words in the path first) with the head of the file as the snippet. Respects
- * .gitignore, and never offers a file `askPath` would refuse.
+ * Every file under `root` worth judging, most promising first. With `pattern`, the files ripgrep
+ * matches with their matched lines; without it, every file ripgrep lists, scored by question words
+ * in the path and (for a set too large to judge file by file) in the content, one fixed-string
+ * ripgrep per word, in parallel. Respects .gitignore, and never offers a file `askPath` would refuse.
  */
-export async function findCandidates(
-	options: { rg: string; cwd: string; root: string; question: string; pattern?: string; glob?: string; ignoreCase?: boolean },
-	snippetBytes: number,
-	signal: AbortSignal | undefined,
-): Promise<{ candidates: FindCandidate[]; total: number }> {
+export async function gatherFindFiles(options: FindGatherOptions, signal: AbortSignal | undefined): Promise<FindFile[]> {
 	// Always name the root: with no path and a piped stdin, rg searches stdin and hangs.
 	// Paths come back as `./src/x.ts`, so they are normalized below.
 	const root = ["--", options.root];
 	const filters = [...(options.glob ? ["--glob", options.glob] : []), ...(options.ignoreCase ? ["-i"] : [])];
 	const allowed = (path: string) => "full" in askPath(path, options.cwd);
+	const words = questionWords(options.question);
 	if (options.pattern) {
 		const out = await runRg(
 			options.rg,
@@ -459,17 +511,11 @@ export async function findCandidates(
 			entry.text.push(`L${match[1]}: ${match[2].trim()}`);
 			byFile.set(path, entry);
 		}
-		const files = [...byFile].filter(([path]) => allowed(path)).sort((a, b) => b[1].lines.length - a[1].lines.length);
-		return {
-			total: files.length,
-			candidates: files.slice(0, MAX_FIND_CANDIDATES).map(([path, entry]) => ({
-				path,
-				lines: entry.lines,
-				snippet: clip(entry.text.join("\n"), snippetBytes).text,
-			})),
-		};
+		return [...byFile]
+			.filter(([path]) => allowed(path))
+			.map(([path, entry]) => ({ path, lines: entry.lines, hits: entry.text, score: entry.lines.length + pathOverlap(path, words) }))
+			.sort(byScore);
 	}
-	const words = questionWords(options.question);
 	const out = await runRg(options.rg, ["--files", "--color=never", ...filters, ...root], options.cwd, signal);
 	const listed = out
 		.split("\n")
@@ -477,9 +523,7 @@ export async function findCandidates(
 		.map((path) => normalize(path))
 		.filter(allowed);
 	const score = new Map(listed.map((path) => [path, pathOverlap(path, words)]));
-	if (listed.length > MAX_FIND_CANDIDATES && words.length > 0) {
-		// More files than Jev judges: a file scores once per distinct question word its content holds,
-		// one fixed-string ripgrep per word, in parallel.
+	if (listed.length > FIND_DIRECT_FILES && words.length > 0) {
 		const hits = await Promise.all(
 			words.map((word) =>
 				runRg(options.rg, ["-l", "-i", "-F", "--color=never", ...filters, "-e", word, ...root], options.cwd, signal),
@@ -493,93 +537,742 @@ export async function findCandidates(
 			}
 		}
 	}
-	const files = listed.map((path) => ({ path })).sort((a, b) => (score.get(b.path) ?? 0) - (score.get(a.path) ?? 0));
-	const candidates: FindCandidate[] = [];
-	for (const { path } of files.slice(0, MAX_FIND_CANDIDATES)) {
-		const file = readBounded(resolve(options.cwd, path), FIND_SCAN_BYTES);
-		if ("error" in file) continue;
-		candidates.push({ path, ...excerpt(file.text, words, snippetBytes) });
-	}
-	return { candidates, total: files.length };
+	return listed.map((path) => ({ path, lines: [], hits: [], score: score.get(path) ?? 0 })).sort(byScore);
+}
+
+// Judging ------------------------------------------------------------------
+
+/** One noul: a keyed piece of state and the question asked about it. */
+export interface JudgeItem {
+	key: string;
+	text: string;
+	question: string;
+}
+
+export interface JudgeStage {
+	request: string;
+	/** Where the items sit in `state` (`directories`, `files`, `units`). */
+	stateKey: string;
+	criteria: { true: string; false: string };
 }
 
-/** One batch as a decisions request: the shared snippets as state, one noul per file. */
-export function buildFindPayload(question: string, batch: readonly FindCandidate[]): Record<string, unknown> {
+/** One request: the items at `items` (indexes into the stage's list), one noul `q<i>` each. */
+export function buildJudgePayload(stage: JudgeStage, items: readonly JudgeItem[]): Record<string, unknown> {
 	return buildAskPayload(
-		batch.map((candidate, index) => ({
-			name: `f${index}`,
-			type: "noul" as const,
-			instructions: `Is the file "${candidate.path}" relevant to the request, judged by its excerpt in state.files?`,
-			criteria: {
-				true: "The excerpt shows this file implements, defines, configures, or directly answers the request.",
-				false: "The file only mentions related words, or is about something else.",
-			},
-		})),
-		{ request: question, files: Object.fromEntries(batch.map((candidate) => [candidate.path, candidate.snippet])) },
+		items.map((item, index) => ({ name: `q${index}`, type: "noul" as const, instructions: item.question, criteria: stage.criteria })),
+		{ request: stage.request, [stage.stateKey]: Object.fromEntries(items.map((item) => [item.key, item.text])) },
 	);
 }
 
 /**
- * The batch's request, its snippets shrunk until the serialized request fits `maxBytes`: code
- * grows under JSON escaping, so a byte budget per snippet alone does not guarantee a fit.
+ * The stage's items as requests that each serialize within `maxBytes`: FIND_BATCH items per
+ * request, their texts shrunk together until the request fits (code grows under JSON escaping, so a
+ * byte budget per text alone does not guarantee a fit). When even empty texts do not fit — the
+ * questions, paths, and scaffolding alone are too large — the batch is halved, and an item that
+ * cannot fit alone is dropped. No request this returns can come back as `overflow`.
+ */
+export function fitJudgePayloads(
+	stage: JudgeStage,
+	items: readonly JudgeItem[],
+	maxBytes: number,
+): { payloads: Array<{ payload: Record<string, unknown>; items: number[] }>; dropped: number[] } {
+	const payloads: Array<{ payload: Record<string, unknown>; items: number[] }> = [];
+	const dropped: number[] = [];
+	const place = (indexes: number[]): void => {
+		let limit = Math.max(0, ...indexes.map((index) => Buffer.byteLength(items[index].text, "utf-8")));
+		for (;;) {
+			const payload = buildJudgePayload(
+				stage,
+				indexes.map((index) => {
+					const text = clip(items[index].text, limit);
+					return { ...items[index], text: text.clipped && limit > 0 ? `${text.text}${TRUNCATION_MARKER}` : text.text };
+				}),
+			);
+			if (serializeJevRequest(payload, maxBytes) !== undefined) {
+				payloads.push({ payload, items: indexes });
+				return;
+			}
+			if (limit > 0) {
+				limit = limit < 64 ? 0 : Math.floor(limit * 0.75);
+				continue;
+			}
+			if (indexes.length === 1) {
+				dropped.push(indexes[0]);
+				return;
+			}
+			const half = Math.ceil(indexes.length / 2);
+			place(indexes.slice(0, half));
+			place(indexes.slice(half));
+			return;
+		}
+	};
+	for (let start = 0; start < items.length; start += FIND_BATCH) {
+		place(Array.from({ length: Math.min(FIND_BATCH, items.length - start) }, (_, offset) => start + offset));
+	}
+	return { payloads, dropped };
+}
+
+/**
+ * The call's Jev requests: every stage sends its batches in parallel (one round trip), retries a
+ * `transport` failure once, and never exceeds FIND_MAX_REQUESTS in total, retries included.
  */
-export function fitFindPayload(question: string, batch: readonly FindCandidate[], maxBytes: number): Record<string, unknown> {
-	let limit = Math.max(0, ...batch.map((candidate) => Buffer.byteLength(candidate.snippet, "utf-8")));
-	for (;;) {
-		const payload = buildFindPayload(
-			question,
-			batch.map((candidate) => ({ ...candidate, snippet: clip(candidate.snippet, limit).text })),
+export class FindRequests {
+	sent = 0;
+	retried = 0;
+	readonly diagnostics: JevFailureDiagnostic[] = [];
+	private readonly ask: JevFindAsk;
+	readonly max: number;
+	constructor(ask: JevFindAsk, max = FIND_MAX_REQUESTS) {
+		this.ask = ask;
+		this.max = max;
+	}
+
+	get left(): number {
+		return this.max - this.sent;
+	}
+
+	/**
+	 * Send up to `sendCap` payloads in parallel, then retry the transport failures within `retryCap`
+	 * total requests for this stage. A payload past the caps comes back undefined (not sent).
+	 */
+	async sendAll(
+		payloads: readonly Record<string, unknown>[],
+		sendCap: number,
+		retryCap = sendCap,
+	): Promise<Array<JevAnswers | undefined>> {
+		const count = Math.max(0, Math.min(payloads.length, sendCap, this.left));
+		this.sent += count;
+		const results: Array<JevAnswers | undefined> = await Promise.all(
+			payloads.slice(0, count).map((payload) => this.ask(payload)),
 		);
-		if (limit < 64 || serializeJevRequest(payload, maxBytes) !== undefined) return payload;
-		limit = Math.floor(limit * 0.75);
+		const retry = results
+			.map((result, index) => ({ result, index }))
+			.filter(({ result }) => result?.failure === "transport")
+			.slice(0, Math.max(0, Math.min(retryCap - count, this.left)));
+		this.sent += retry.length;
+		this.retried += retry.length;
+		const again = await Promise.all(retry.map(({ index }) => this.ask(payloads[index])));
+		retry.forEach(({ index }, k) => {
+			results[index] = again[k];
+		});
+		for (const result of results) {
+			const diagnostic = result?.diagnostic;
+			if (diagnostic && !this.diagnostics.some((item) => item.kind === diagnostic.kind && item.httpStatus === diagnostic.httpStatus)) {
+				this.diagnostics.push(diagnostic);
+			}
+		}
+		return [...results, ...Array.from({ length: payloads.length - count }, () => undefined)];
 	}
 }
 
-/** Pointers only: path, matched lines, relevance. File contents never reach the agent. */
-export function renderFindResults(input: {
-	ranked: ReadonlyArray<FindCandidate & { relevance?: number }>;
-	total: number;
-	judged: number;
-	limit: number;
+interface JudgeOutcome {
+	/** Jev's noul per item; undefined when it was not answered. */
+	scores: Array<number | undefined>;
+	/** Why unanswered items went unanswered: a request failure, `request cap`, or `too large`. */
+	reasons: string[];
+}
+
+/** Ask one noul per item, batched and fitted, within the stage's request caps. */
+async function judgeNouls(
+	requests: FindRequests,
+	stage: JudgeStage,
+	items: readonly JudgeItem[],
+	maxBytes: number,
+	caps: { send: number; retry: number },
+): Promise<JudgeOutcome> {
+	const scores: Array<number | undefined> = items.map(() => undefined);
+	const reasons: string[] = [];
+	if (items.length === 0) return { scores, reasons };
+	const fitted = fitJudgePayloads(stage, items, maxBytes);
+	if (fitted.dropped.length > 0) reasons.push("too large");
+	const results = await requests.sendAll(
+		fitted.payloads.map((entry) => entry.payload),
+		caps.send,
+		caps.retry,
+	);
+	fitted.payloads.forEach((entry, p) => {
+		const result = results[p];
+		if (!result) {
+			reasons.push("request cap");
+			return;
+		}
+		if (result.failure) reasons.push(result.failure);
+		const answers = result.answers ?? {};
+		entry.items.forEach((index, k) => {
+			const answer = answers[`q${k}`];
+			if (isRecord(answer) && typeof answer.noul === "number") scores[index] = answer.noul;
+		});
+	});
+	return { scores, reasons: [...new Set(reasons)] };
+}
+
+// Directory descent --------------------------------------------------------
+
+const DIRECTORY_CRITERIA = {
+	true: "Its name, file names, or keyword hits suggest it holds code that implements, defines, or configures what the request asks about.",
+	false: "It clearly holds something unrelated to the request.",
+};
+
+/** The directory one level below `dir` that holds `path`, or undefined when `path` sits directly in `dir`. */
+export function childDirectory(path: string, dir: string): string | undefined {
+	const rest = dir === "." ? path : path.slice(dir.length + 1);
+	const cut = rest.indexOf(sep);
+	if (cut < 0) return undefined;
+	return dir === "." ? rest.slice(0, cut) : `${dir}${sep}${rest.slice(0, cut)}`;
+}
+
+/** What Jev reads of a directory: its size, its most promising file names, and a few keyword hits. */
+function describeDirectory(dir: string, files: readonly FindFile[], hitLines: (file: FindFile) => string[]): string {
+	const ordered = [...files].sort(byScore);
+	const local = (path: string) => path.slice(dir.length + 1);
+	const names = ordered.slice(0, FIND_DIR_FILE_NAMES).map((file) => local(file.path));
+	const more = files.length - names.length;
+	const hits: string[] = [];
+	for (const file of ordered.filter((candidate) => candidate.score > 0).slice(0, FIND_DIR_HIT_LINES)) {
+		for (const line of hitLines(file).slice(0, 2)) {
+			if (hits.length < FIND_DIR_HIT_LINES) hits.push(`${local(file.path)} ${line.slice(0, 160)}`);
+		}
+	}
+	return [
+		`${files.length} file(s): ${names.join(", ")}${more > 0 ? `, … (+${more} more)` : ""}`,
+		...(hits.length > 0 ? ["Keyword hits:", ...hits] : []),
+	].join("\n");
+}
+
+export interface DescentResult {
+	/** Files still worth judging: those in kept directories, and those sitting directly in a descended one. */
+	kept: FindFile[];
+	prunedDirs: number;
+	prunedFiles: number;
+	/** Directories kept without an answer, and why. */
+	unjudgedDirs: number;
+	reasons: string[];
+}
+
+/**
+ * Narrow a large file set directory by directory: one noul per next-level directory ("could this
+ * hold the answer?"), all of a level in one parallel round trip. A directory below FIND_DIR_KEEP is
+ * dropped with every file under it; an unanswered one is kept (unknown is not rejected). Kept
+ * directories still larger than FIND_DIRECT_FILES are descended again, up to FIND_MAX_DEPTH
+ * levels; a lone subdirectory is entered without a question.
+ */
+export async function narrowByDirectory(
+	files: readonly FindFile[],
+	root: string,
+	options: { request: string; maxBytes: number; requests: FindRequests; hitLines: (file: FindFile) => string[] },
+): Promise<DescentResult> {
+	const result: DescentResult = { kept: [], prunedDirs: 0, prunedFiles: 0, unjudgedDirs: 0, reasons: [] };
+	if (files.length <= FIND_DIRECT_FILES) return { ...result, kept: [...files] };
+	let pending: Array<{ dir: string; files: FindFile[]; depth: number }> = [{ dir: root, files: [...files], depth: 0 }];
+	let dirRequests = 0;
+	while (pending.length > 0) {
+		const children: Array<{ dir: string; files: FindFile[]; depth: number; free: boolean }> = [];
+		for (const group of pending) {
+			const byChild = new Map<string, FindFile[]>();
+			let direct = 0;
+			for (const file of group.files) {
+				const child = childDirectory(file.path, group.dir);
+				if (child === undefined) {
+					result.kept.push(file);
+					direct += 1;
+				} else {
+					byChild.set(child, [...(byChild.get(child) ?? []), file]);
+				}
+			}
+			const free = byChild.size === 1 && direct === 0;
+			for (const [dir, under] of byChild) children.push({ dir, files: under, depth: group.depth + 1, free });
+		}
+		const sendCap = Math.min(FIND_DIR_REQUESTS - dirRequests, options.requests.left - FIND_UNIT_REQUESTS - 1);
+		const questionable = children.filter((child) => !child.free && child.depth <= FIND_MAX_DEPTH);
+		const asked =
+			sendCap > 0
+				? questionable.sort(
+						(a, b) => b.files.reduce((sum, f) => sum + f.score, 0) - a.files.reduce((sum, f) => sum + f.score, 0),
+					)
+				: [];
+		if (children.some((child) => !child.free && child.depth > FIND_MAX_DEPTH)) result.reasons.push("depth limit");
+		if (questionable.length > 0 && asked.length === 0) result.reasons.push("request cap");
+		const verdicts = new Map<string, number | undefined>();
+		if (asked.length > 0) {
+			const before = options.requests.sent;
+			const outcome = await judgeNouls(
+				options.requests,
+				{ request: options.request, stateKey: "directories", criteria: DIRECTORY_CRITERIA },
+				asked.map((child) => ({
+					key: `${child.dir}${sep}`,
+					text: describeDirectory(child.dir, child.files, options.hitLines),
+					question: `Could the directory "${child.dir}${sep}" contain code that answers the request, judged by its description in state.directories?`,
+				})),
+				options.maxBytes,
+				{ send: sendCap, retry: sendCap },
+			);
+			dirRequests += options.requests.sent - before;
+			asked.forEach((child, index) => verdicts.set(child.dir, outcome.scores[index]));
+			result.reasons.push(...outcome.reasons);
+		}
+		const next: typeof pending = [];
+		for (const child of children) {
+			const wasAsked = verdicts.has(child.dir);
+			const verdict = verdicts.get(child.dir);
+			if (verdict !== undefined && verdict < FIND_DIR_KEEP) {
+				result.prunedDirs += 1;
+				result.prunedFiles += child.files.length;
+				continue;
+			}
+			if (verdict === undefined && !child.free) result.unjudgedDirs += 1;
+			const canDescend = child.depth < FIND_MAX_DEPTH && (child.free || wasAsked);
+			if (child.files.length > FIND_DIRECT_FILES && canDescend) {
+				next.push({ dir: child.dir, files: child.files, depth: child.depth });
+			} else result.kept.push(...child.files);
+		}
+		pending = next;
+	}
+	result.reasons = [...new Set(result.reasons)];
+	return result;
+}
+
+// Source units -------------------------------------------------------------
+
+const FILE_CRITERIA = {
+	true: "The excerpt shows this file implements, defines, configures, or directly answers the request.",
+	false: "The file only mentions related words, or is about something else.",
+};
+
+const UNIT_CRITERIA = {
+	true: "This unit implements, defines, configures, or directly answers what the request asks.",
+	false: "The unit only mentions related words, or does something else.",
+};
+
+/** A unit's candidate score: matched/keyword lines inside it weigh most, then distinct question words. */
+export function pickUnits(
+	units: readonly SourceUnit[],
+	rows: readonly string[],
+	hits: readonly number[],
+	words: readonly string[],
+): SourceUnit[] {
+	const bodies = units.filter((unit) => unit.name !== "imports");
+	const scored = bodies.map((unit) => {
+		const body = rows.slice(unit.start - 1, unit.end).join("\n").toLowerCase();
+		const hitCount = hits.filter((line) => line >= unit.start && line <= unit.end).length;
+		return { unit, score: hitCount * 10 + words.filter((word) => body.includes(word)).length };
+	});
+	const picks = scored
+		.filter((entry) => entry.score > 0)
+		.sort((a, b) => b.score - a.score || a.unit.start - b.unit.start)
+		.slice(0, FIND_UNITS_PER_FILE)
+		.map((entry) => entry.unit);
+	// Nothing matched a word: let Jev judge the file's first declarations.
+	return (picks.length > 0 ? picks : bodies.slice(0, 3)).sort((a, b) => a.start - b.start);
+}
+
+/**
+ * The line numbers a unit is shown as (0 marks elided lines): the header line of a member, then the
+ * unit whole, or — when it is longer than `maxLines` — its first line and a window from just above
+ * its best keyword line (`focus`), so a long function shows where the asked-about behavior sits.
+ */
+export function unitView(unit: SourceUnit, focus: number | undefined, maxLines = FIND_UNIT_MAX_LINES): number[] {
+	const view: number[] = unit.header !== undefined && unit.header < unit.start ? [unit.header, 0] : [];
+	const range = (from: number, to: number) => Array.from({ length: Math.max(0, to - from + 1) }, (_, i) => from + i);
+	if (unit.end - unit.start + 1 <= maxLines) return [...view, ...range(unit.start, unit.end)];
+	if (focus === undefined || focus < unit.start + maxLines - FIND_FOCUS_LEAD) {
+		return [...view, ...range(unit.start, unit.start + maxLines - 1), 0];
+	}
+	const from = Math.max(unit.start + 1, focus - FIND_FOCUS_LEAD);
+	const to = Math.min(unit.end, from + maxLines - 2);
+	return [...view, unit.start, ...(from > unit.start + 1 ? [0] : []), ...range(from, to), ...(to < unit.end ? [0] : [])];
+}
+
+/** The first `hits` line inside the unit, in `hits` order (best first). */
+function focusOf(unit: SourceUnit, hits: readonly number[]): number | undefined {
+	return hits.find((line) => line >= unit.start && line <= unit.end);
+}
+
+/** A file's rows without carriage returns (and without the empty row after a final newline), so numbered lines print as they read. */
+function fileRows(text: string): string[] {
+	const rows = text.split("\n").map((row) => row.replace(/\r$/, ""));
+	if (rows.length > 1 && rows.at(-1) === "") rows.pop();
+	return rows;
+}
+
+interface SourceBlock {
+	path: string;
+	unit: SourceUnit;
+	view: number[];
+	rows: readonly string[];
+}
+
+/**
+ * `Source block "path" lines a-b:` and the numbered verbatim lines of each block, in order, within
+ * `budgetBytes` of source; a block cut by the budget ends in `…`, and one that cannot show three
+ * lines is left out.
+ */
+export function renderSourceBlocks(
+	blocks: readonly SourceBlock[],
+	budgetBytes = FIND_MAX_SOURCE_BYTES,
+): { lines: string[]; bytes: number; omitted: number } {
+	const lines: string[] = [];
+	let bytes = 0;
+	let omitted = 0;
+	for (const block of blocks) {
+		const numbered: string[] = [];
+		let used = 0;
+		let cut = false;
+		for (const line of block.view) {
+			const text = line === 0 ? "…" : `${line}: ${block.rows[line - 1] ?? ""}`;
+			const size = Buffer.byteLength(text, "utf-8") + 1;
+			if (bytes + used + size > budgetBytes) {
+				cut = true;
+				break;
+			}
+			numbered.push(text);
+			used += size;
+		}
+		if (numbered.filter((text) => text !== "…").length < Math.min(3, block.view.filter((line) => line !== 0).length)) {
+			omitted += 1;
+			continue;
+		}
+		if (cut && numbered.at(-1) !== "…") numbered.push("…");
+		lines.push("", `Source block "${block.path}" lines ${block.unit.start}-${block.unit.end}:`, ...numbered);
+		bytes += used;
+	}
+	return { lines, bytes, omitted };
+}
+
+/** Keyword lines for a directory description or a fallback window: rg's matches, or the file's best question-word lines. */
+function keywordLines(text: string | undefined, words: readonly string[]): { lines: number[]; snippet: string[] } {
+	if (text === undefined || words.length === 0) return { lines: [], snippet: [] };
+	const found = excerpt(text, words, FIND_SCAN_BYTES);
+	return found.lines.length === 0 ? { lines: [], snippet: [] } : { lines: found.lines, snippet: found.snippet.split("\n") };
+}
+
+function fallbackSourceUnits(
+	path: string,
+	text: string,
+	ts: Awaited<ReturnType<typeof loadTypeScript>>,
+	rows: readonly string[],
+	hits: readonly number[],
+	words: readonly string[],
+): SourceUnit[] {
+	if (hits.length === 0) return [];
+	return pickUnits(splitSourceUnits(path, text, ts), rows, hits, words).filter((unit) =>
+		hits.some((line) => (line >= unit.start && line <= unit.end) || line === unit.header),
+	);
+}
+
+function formatJevDiagnostic(diagnostic: JevFailureDiagnostic): string {
+	if (diagnostic.kind === "timeout") return "Jev request timed out.";
+	if (diagnostic.kind === "malformed-response") return "Jev returned a malformed response.";
+	return `Jev provider request failed${diagnostic.httpStatus ? ` (HTTP ${diagnostic.httpStatus})` : ""}.`;
+}
+
+// The whole call -----------------------------------------------------------
+
+export interface JevFindOptions extends FindGatherOptions {
+	limit?: number;
+	/** The route's request budget; no request is sent larger than this. */
+	maxBytes: number;
 	model: string;
-	elapsedMs: number;
+	/** Sends one request; absent when Jev is out of reach (`unreachable` says why). */
+	ask?: JevFindAsk;
+	unreachable?: JevAbstainReason;
+	/** The TypeScript loader; tests pass one resolving undefined to force chunking. */
+	loadTypeScript?: typeof loadTypeScript;
+	signal?: AbortSignal;
+}
+
+export interface JevFindResult {
+	text: string;
+	/** Shape only, like ask_jev: details persist in the session. */
+	details: Record<string, unknown>;
+	judged: number;
+	topRelevance?: number;
 	failure?: string;
-}): string {
-	const pointer = (candidate: FindCandidate) =>
-		candidate.lines.length > 0 ? `${candidate.path}:${candidate.lines.slice(0, 4).join(",")}` : candidate.path;
-	if (input.total === 0) return "jev_find: no candidate files. Loosen `pattern`, `glob`, or `path`.";
-	const lines: string[] = [];
-	if (input.judged === 0) {
-		lines.push(
-			`jev_find: Jev did not judge (${input.failure ?? "missing"}); ${input.total} candidate file(s), unranked by relevance:`,
-			...input.ranked.slice(0, input.limit).map((candidate) => `- ${pointer(candidate)}`),
+	elapsedMs: number;
+}
+
+/**
+ * The whole jev_find call: gather files with ripgrep, narrow large sets by directory, judge files,
+ * then judge the source units of the relevant ones and return them verbatim. Without a reachable
+ * Jev (or when no file could be judged) the ripgrep-ranked list still comes back, with keyword
+ * windows of the top files, so the call is never wasted. Throws only when ripgrep fails.
+ */
+export async function runJevFind(options: JevFindOptions): Promise<JevFindResult> {
+	const files = await gatherFindFiles(options, options.signal);
+	if (files.length === 0) {
+		return {
+			text: "jev_find: no candidate files. Loosen `pattern`, `glob`, or `path`.",
+			details: { total: 0, judged: 0 },
+			judged: 0,
+			elapsedMs: 0,
+		};
+	}
+	const words = questionWords(options.question);
+	const limit = Math.max(1, Math.floor(options.limit ?? FIND_DEFAULT_LIMIT));
+	const texts = new Map<string, string | undefined>();
+	const readText = (path: string): string | undefined => {
+		if (!texts.has(path)) {
+			const file = readBounded(resolve(options.cwd, path), FIND_SCAN_BYTES);
+			texts.set(path, "error" in file ? undefined : file.text);
+		}
+		return texts.get(path);
+	};
+	const hitsOf = (file: FindFile): { lines: number[]; snippet: string[] } =>
+		file.lines.length > 0 ? { lines: file.lines, snippet: file.hits } : keywordLines(readText(file.path), words);
+
+	/** The ripgrep-ranked list and source units of the top files: what comes back when Jev did not rank. */
+	const fallback = async (
+		reason: string,
+		notes: string[],
+		elapsedMs: number,
+		requests?: FindRequests,
+	): Promise<JevFindResult> => {
+		const shown = files.slice(0, limit);
+		const sourceFiles = shown.slice(0, FIND_FALLBACK_SOURCE_FILES);
+		const ts = sourceFiles.some((file) => isScriptPath(file.path)) ? await (options.loadTypeScript ?? loadTypeScript)() : undefined;
+		const blocks: SourceBlock[] = [];
+		const leads = new Map<string, string>();
+		for (const file of sourceFiles) {
+			const text = readText(file.path);
+			if (text === undefined) continue;
+			const rows = fileRows(text);
+			const hits = hitsOf(file).lines;
+			const units = fallbackSourceUnits(file.path, text, ts, rows, hits, words);
+			const selected = units.length > 0 ? units : keywordWindows(rows.length, hits);
+			leads.set(file.path, selected.map((unit) => `${unit.name} lines ${unit.start}-${unit.end}`).join(", "));
+			for (const unit of selected) blocks.push({ path: file.path, unit, view: unitView(unit, focusOf(unit, hits)), rows });
+		}
+		const source = renderSourceBlocks(blocks);
+		const diagnostic = requests?.diagnostics[0];
+		const lines = [
+			`jev_find: Jev did not judge (${reason}); ${files.length} candidate file(s), ranked by ripgrep:`,
+			...notes,
+			...(diagnostic ? [`Diagnostic: ${formatJevDiagnostic(diagnostic)}`] : []),
+			...shown.map((file) => `- ${file.path}${leads.has(file.path) ? ` — ${leads.get(file.path)}` : ""}`),
+			...(files.length > shown.length ? [`${files.length - shown.length} more candidate file(s) not listed.`] : []),
+			...source.lines,
+			"",
+			"End context.",
+		];
+		return {
+			text: lines.join("\n"),
+			details: {
+				total: files.length,
+				judged: 0,
+				requests: requests?.sent ?? 0,
+				sourceBytes: source.bytes,
+				elapsedMs,
+				failure: reason,
+				...(diagnostic ? { diagnostic } : {}),
+			},
+			judged: 0,
+			failure: reason,
+			...(diagnostic ? { diagnostic } : {}),
+			elapsedMs,
+		};
+	};
+
+	if (!options.ask) return fallback(options.unreachable ?? "missing", [], 0);
+
+	const started = Date.now();
+	const requests = new FindRequests(options.ask);
+	const request = clip(options.question, FIND_REQUEST_BYTES).text;
+	const notes: string[] = [];
+
+	// 1. Directories.
+	const descent = await narrowByDirectory(files, options.root, {
+		request,
+		maxBytes: options.maxBytes,
+		requests,
+		hitLines: (file) => hitsOf(file).snippet,
+	});
+	if (descent.prunedDirs > 0) {
+		notes.push(`Jev ruled out ${descent.prunedDirs} director${descent.prunedDirs === 1 ? "y" : "ies"} holding ${descent.prunedFiles} file(s).`);
+	}
+	if (descent.unjudgedDirs > 0) {
+		notes.push(
+			`${descent.unjudgedDirs} director${descent.unjudgedDirs === 1 ? "y was" : "ies were"} kept unjudged (${descent.reasons.join(", ") || "missing"}).`,
 		);
-	} else {
-		const strong = input.ranked.filter((candidate) => (candidate.relevance ?? 0) >= FIND_MIN_RELEVANCE);
-		lines.push(`jev_find: judged ${input.judged} of ${input.total} candidate file(s) via ${input.model} in ${input.elapsedMs}ms`);
-		const shown = strong.length > 0 ? strong.slice(0, input.limit) : input.ranked.slice(0, 3);
-		if (strong.length === 0) lines.push("No file is a confident match; the closest were:");
-		for (const candidate of shown) {
-			lines.push(`- ${pointer(candidate)} (${candidate.relevance === undefined ? "not judged" : candidate.relevance.toFixed(2)})`);
+	}
+
+	// 2. Files, best score first, within the judging cap and the requests left after the unit reserve.
+	const fileSendCap = requests.left - FIND_UNIT_REQUESTS;
+	const judgeCap = Math.min(FIND_MAX_JUDGED_FILES, Math.max(0, fileSendCap) * FIND_BATCH);
+	const ordered = [...descent.kept].sort(byScore);
+	const pastCap = Math.max(0, ordered.length - judgeCap);
+	const snippetBytes = Math.max(256, Math.floor((options.maxBytes - FIND_QUESTION_RESERVE) / FIND_BATCH));
+	const candidates: FindCandidate[] = [];
+	for (const file of ordered.slice(0, judgeCap)) {
+		if (file.lines.length > 0) {
+			candidates.push({ path: file.path, lines: file.lines, snippet: clip(file.hits.join("\n"), snippetBytes).text });
+			continue;
 		}
-		if (strong.length > shown.length) lines.push(`${strong.length - shown.length} more relevant file(s) past the limit.`);
+		const text = readText(file.path);
+		if (text !== undefined) candidates.push({ path: file.path, ...excerpt(text, words, snippetBytes) });
 	}
-	if (input.total > MAX_FIND_CANDIDATES) {
-		lines.push(`${input.total - MAX_FIND_CANDIDATES} candidate(s) were not judged; narrow with \`pattern\`, \`glob\`, or \`path\`.`);
+	const filesOutcome = await judgeNouls(
+		requests,
+		{ request, stateKey: "files", criteria: FILE_CRITERIA },
+		candidates.map((candidate) => ({
+			key: candidate.path,
+			text: candidate.snippet,
+			question: `Is the file "${candidate.path}" relevant to the request, judged by its excerpt in state.files?`,
+		})),
+		options.maxBytes,
+		// A retry may borrow one request from the unit reserve: without file verdicts there is nothing to excerpt.
+		{ send: fileSendCap, retry: requests.left - 1 },
+	);
+	const scored = candidates.map((candidate, index) => ({ ...candidate, relevance: filesOutcome.scores[index] }));
+	const judged = scored.filter((candidate) => candidate.relevance !== undefined).length;
+	const unjudgedFiles = candidates.length - judged;
+	if (pastCap > 0) {
+		notes.push(`${pastCap} file(s) past the ${judgeCap}-file judging cap were not judged; narrow with \`pattern\`, \`glob\`, or \`path\`.`);
+	}
+	if (judged === 0) {
+		return fallback(filesOutcome.reasons[0] ?? "missing", notes, Date.now() - started, requests);
+	}
+	if (unjudgedFiles > 0) notes.push(`${unjudgedFiles} file(s) were not judged (${filesOutcome.reasons.join(", ") || "missing"}).`);
+
+	const ranked = scored
+		.filter((candidate): candidate is FindCandidate & { relevance: number } => candidate.relevance !== undefined)
+		.sort((a, b) => b.relevance - a.relevance);
+	const relevant = ranked.filter((candidate) => candidate.relevance >= FIND_MIN_RELEVANCE);
+	const shown = relevant.slice(0, limit);
+
+	// 3. Source units of the relevant files, in relevance order, within the requests left.
+	const ts = shown.some((candidate) => isScriptPath(candidate.path))
+		? await (options.loadTypeScript ?? loadTypeScript)()
+		: undefined;
+	const perFile = shown.map((candidate) => {
+		const text = readText(candidate.path) ?? "";
+		const rows = fileRows(text);
+		const hits = [...new Set([...candidate.lines, ...keywordLines(text, words).lines])];
+		const picks = text === "" ? [] : pickUnits(splitSourceUnits(candidate.path, text, ts), rows, hits, words);
+		return { candidate, rows, hits, picks };
+	});
+	const unitItems: JudgeItem[] = [];
+	const owners: Array<{ file: number; unit: SourceUnit }> = [];
+	const unitCapacity = requests.left * FIND_BATCH;
+	perFile.forEach((entry, file) => {
+		for (const unit of entry.picks) {
+			if (unitItems.length >= unitCapacity) return;
+			const key = `${entry.candidate.path} lines ${unit.start}-${unit.end} (${unit.name})`;
+			unitItems.push({
+				key,
+				text: unitView(unit, focusOf(unit, entry.hits))
+					.map((line) => (line === 0 ? "…" : (entry.rows[line - 1] ?? "")))
+					.join("\n"),
+				question: `Does the source unit "${key}" in state.units implement, define, configure, or directly answer the request?`,
+			});
+			owners.push({ file, unit });
+		}
+	});
+	const unitsOutcome = await judgeNouls(
+		requests,
+		{ request, stateKey: "units", criteria: UNIT_CRITERIA },
+		unitItems,
+		options.maxBytes,
+		{ send: requests.left, retry: requests.left },
+	);
+	const elapsedMs = Date.now() - started;
+
+	const blocks: SourceBlock[] = [];
+	const listing: string[] = [];
+	let windowed = 0;
+	perFile.forEach((entry, file) => {
+		const judgedUnits = owners
+			.map((owner, index) => ({ ...owner, score: unitsOutcome.scores[index] }))
+			.filter((owner) => owner.file === file);
+		const answered = judgedUnits.some((owner) => owner.score !== undefined);
+		const fallbackUnits = fallbackSourceUnits(
+			entry.candidate.path,
+			readText(entry.candidate.path) ?? "",
+			ts,
+			entry.rows,
+			entry.hits,
+			words,
+		);
+		const units =
+			answered || entry.rows.length === 0 || entry.picks.length === 0
+				? judgedUnits.filter((owner) => (owner.score ?? 0) >= FIND_MIN_RELEVANCE).map((owner) => owner.unit)
+				: fallbackUnits.length > 0
+					? fallbackUnits
+					: keywordWindows(entry.rows.length, entry.hits);
+		if (!answered && units.length > 0) windowed += 1;
+		for (const unit of units) {
+			blocks.push({ path: entry.candidate.path, unit, view: unitView(unit, focusOf(unit, entry.hits)), rows: entry.rows });
+		}
+		const leads = units.map((unit) => `${unit.name} lines ${unit.start}-${unit.end}`).join(", ");
+		listing.push(`- ${entry.candidate.path} (${entry.candidate.relevance.toFixed(2)})${leads ? ` — reading leads: ${leads}` : ""}`);
+	});
+	if (windowed > 0) {
+		notes.push(
+			`Jev did not judge the source units of ${windowed} file(s) (${unitsOutcome.reasons.join(", ") || "missing"}); matching source units or keyword windows are shown instead.`,
+		);
+	}
+	if (relevant.length > shown.length) {
+		const rest = relevant.slice(shown.length);
+		notes.push(
+			`${rest.length} more relevant file(s) past the limit: ${rest
+				.slice(0, 5)
+				.map((candidate) => `${candidate.path} (${candidate.relevance.toFixed(2)})`)
+				.join(", ")}${rest.length > 5 ? ", …" : ""}.`,
+		);
+	}
+	const source = renderSourceBlocks(blocks);
+	const diagnostic = requests.diagnostics[0];
+	if (diagnostic) notes.push(`Diagnostic: ${formatJevDiagnostic(diagnostic)}`);
+	if (source.omitted > 0) {
+		notes.push(`${source.omitted} source block(s) left out to stay within ${FIND_MAX_SOURCE_BYTES / 1024} KB; read them from the leads.`);
 	}
-	lines.push("Only pointers are returned; read the files you need.");
-	return lines.join("\n");
+
+	const lines = [
+		`jev_find: ${relevant.length} relevant file(s) (judged ${judged} of ${files.length} candidates via ${options.model} in ${elapsedMs}ms)`,
+		...notes,
+		...(shown.length > 0
+			? listing
+			: [
+					"No file is a confident match; the closest were:",
+					...ranked.slice(0, 3).map((candidate) => `- ${candidate.path} (${candidate.relevance.toFixed(2)})`),
+				]),
+		...source.lines,
+		"",
+		"End context.",
+	];
+	const failure = filesOutcome.reasons.find((reason) => reason !== "request cap" && reason !== "too large");
+	return {
+		text: lines.join("\n"),
+		details: {
+			total: files.length,
+			judged,
+			relevant: relevant.length,
+			requests: requests.sent,
+			retried: requests.retried,
+			sourceBytes: source.bytes,
+			elapsedMs,
+			...(failure ? { failure } : {}),
+			...(diagnostic ? { diagnostic } : {}),
+		},
+		judged,
+		topRelevance: ranked[0]?.relevance,
+		...(failure ? { failure } : {}),
+		...(diagnostic ? { diagnostic } : {}),
+		elapsedMs,
+	};
 }
 
 const JevFindParams = Type.Object({
-	question: Type.String({ description: "What you are looking for, in plain words (e.g. 'where is the retry backoff configured')." }),
+	question: Type.String({
+		description: "What you want to understand, in plain words (e.g. 'how is the retry backoff configured').",
+	}),
 	pattern: Type.Optional(
-		Type.String({ description: "ripgrep regex to narrow candidates to files that match; omit to judge every listed file." }),
+		Type.String({ description: "ripgrep regex to narrow candidates to files that match; omit to consider every listed file." }),
 	),
 	glob: Type.Optional(Type.String({ description: "File glob filter, e.g. '*.ts' or 'src/**/*.md'." })),
 	path: Type.Optional(Type.String({ description: "Directory to search, inside the working directory (default: '.')." })),
 	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive pattern." })),
-	limit: Type.Optional(Type.Number({ description: `Most results to return (default ${FIND_DEFAULT_LIMIT}).` })),
+	limit: Type.Optional(
+		Type.Number({ description: `Most relevant files to return, with their source (default ${FIND_DEFAULT_LIMIT}).` }),
+	),
 });
 
 // ---------------------------------------------------------------------------
@@ -809,19 +1502,23 @@ export default function jevAskToolExtension(pi: ExtensionAPI): void {
 		name: JEV_FIND_TOOL,
 		label: "Jev Find",
 		description: [
-			"Find which files answer a question without reading them: ripgrep gathers candidate files (those matching",
-			"`pattern`, or every file under `path` filtered by `glob`), and Jev judges each file's excerpt against",
-			"`question` in one parallel round trip. Returns ranked `path:lines (relevance)` pointers, never contents.",
-			`Judges up to ${MAX_FIND_CANDIDATES} files per call; respects .gitignore; secret-named files are never sent.`,
+			"Find where behavior lives and read it in one call. ripgrep gathers candidate files (those matching `pattern`,",
+			"or every file under `path` filtered by `glob`); Jev narrows a large tree directory by directory, judges each",
+			"remaining file's excerpt against `question`, then judges the functions, classes, and sections of the relevant",
+			"files. Returns the relevant files with reading leads AND the accepted source verbatim with original line",
+			`numbers (about ${FIND_MAX_SOURCE_BYTES / 1024} KB of source, at most ${FIND_MAX_REQUESTS} Jev requests per call).`,
+			"Respects .gitignore; secret-named files are never sent.",
 		].join(" "),
-		promptSnippet: "Find the files that answer a question: ripgrep candidates ranked by Jev, pointers only",
+		promptSnippet: "Find where behavior lives: Jev-judged relevant files plus their verbatim source with line numbers",
 		promptGuidelines: [
-			"When you look for code by what it does rather than by an exact identifier you already know, call jev_find first — before grep, find, ls, or reading candidate files. One call ranks up to 48 files in about a second and returns file:line pointers; then read only the top ones. Pass `question` in plain words; add `pattern` when you know a likely identifier, `glob`/`path` to scope it.",
-			"Use grep for an exact string or identifier you already know; use jev_find when you would otherwise grep several guesses or read files to see which one is relevant.",
+			"Use jev_find for how/why/where-does-this-behavior-live questions — even when the question names a function or setting — before grep, find, ls, or reading candidate files. One call returns the relevant files and their relevant source verbatim with line numbers. Pass `question` in plain words; add `pattern` when you know a likely identifier, `glob`/`path` to scope it.",
+			"Read the source blocks jev_find returns before searching again; `read` only the leads you still need (to edit, or past a clipped block).",
+			"Use grep or read instead for an exact string, a known symbol's definition, or a known filename.",
+			"When delegating repository discovery to a subagent, tell it to start with jev_find.",
 		],
 		discovery: {
-			summary: "Semantic file finder: ripgrep candidates ranked by Jev relevance",
-			aliases: ["jevgrep", "find", "search", "locate"],
+			summary: "Semantic code finder: Jev-judged relevant files and their verbatim source excerpts",
+			aliases: ["jevgrep", "jg", "find", "search", "locate"],
 			category: "Decisions",
 		},
 		parameters: JevFindParams,
@@ -848,79 +1545,41 @@ export default function jevAskToolExtension(pi: ExtensionAPI): void {
 			const rg = await ensureTool("rg");
 			if (!rg) return text("jev_find needs ripgrep (rg), which is not available; use grep instead.");
 
-			const snippetBytes = Math.max(256, Math.floor((route.payloadBytes - FIND_QUESTION_RESERVE) / FIND_BATCH));
-			let found: { candidates: FindCandidate[]; total: number };
+			// Without Jev the ripgrep-ranked files and their keyword lines still come back: the call is never wasted.
+			const connection = jevConnection(config, route);
+			const unreachable = await jevUnavailable(ctx, connection);
+			let result: JevFindResult;
 			try {
-				found = await findCandidates(
-					{
-						rg,
-						cwd: ctx.cwd,
-						root: inside === "" ? "." : inside,
-						question,
-						pattern: params.pattern || undefined,
-						glob: params.glob || undefined,
-						ignoreCase: params.ignoreCase,
-					},
-					snippetBytes,
+				result = await runJevFind({
+					rg,
+					cwd: ctx.cwd,
+					root: inside === "" ? "." : inside,
+					question,
+					pattern: params.pattern || undefined,
+					glob: params.glob || undefined,
+					ignoreCase: params.ignoreCase,
+					limit: params.limit,
+					maxBytes: route.payloadBytes,
+					model: config.model,
+					...(unreachable
+						? { unreachable }
+						: { ask: (payload) => askJevAnswers(ctx, connection, { payload, maxBytes: route.payloadBytes }) }),
 					signal,
-				);
+				});
 			} catch (error) {
 				return text(`jev_find: ripgrep failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)}).`);
 			}
-			const limit = Math.max(1, Math.floor(params.limit ?? FIND_DEFAULT_LIMIT));
-			const { candidates, total } = found;
-			if (candidates.length === 0) {
-				return text(renderFindResults({ ranked: [], total: 0, judged: 0, limit, model: config.model, elapsedMs: 0 }));
-			}
-
-			// Without Jev the candidates are still worth returning: the call is never wasted.
-			const connection = jevConnection(config, route);
-			const unreachable = await jevUnavailable(ctx, connection);
-			const batches: FindCandidate[][] = [];
-			for (let start = 0; start < candidates.length; start += FIND_BATCH) {
-				batches.push(candidates.slice(start, start + FIND_BATCH));
-			}
-			const started = Date.now();
-			const results = unreachable
-				? []
-				: await Promise.all(
-						batches.map((batch) =>
-							askJevAnswers(ctx, connection, {
-								payload: fitFindPayload(question, batch, route.payloadBytes),
-								maxBytes: route.payloadBytes,
-							}),
-						),
-					);
-			const elapsedMs = Date.now() - started;
-
-			const scored: Array<FindCandidate & { relevance?: number }> = [];
-			let judged = 0;
-			batches.forEach((batch, b) => {
-				const answers = results[b]?.answers ?? {};
-				batch.forEach((candidate, i) => {
-					const answer = answers[`f${i}`];
-					const relevance = isRecord(answer) && typeof answer.noul === "number" ? answer.noul : undefined;
-					if (relevance !== undefined) judged += 1;
-					scored.push({ ...candidate, ...(relevance === undefined ? {} : { relevance }) });
+			if (result.details.total !== 0) {
+				emitJevTelemetry(pi.events, "decision", {
+					route: "find",
+					outcome: result.judged > 0 ? "jev" : "fallback",
+					candidates: result.details.total,
+					confidence: confidenceBucket(result.topRelevance),
+					elapsedMs: result.elapsedMs,
+					...(result.judged > 0 ? {} : { reason: result.failure ?? "missing" }),
 				});
-			});
-			// Judged files by relevance; unjudged ones keep ripgrep's order behind them.
-			const ranked = judged > 0 ? [...scored].sort((a, b) => (b.relevance ?? -1) - (a.relevance ?? -1)) : scored;
-			const failure = unreachable ?? results.find((result) => result.failure)?.failure;
-
-			emitJevTelemetry(pi.events, "decision", {
-				route: "find",
-				outcome: judged > 0 ? "jev" : "fallback",
-				candidates: candidates.length,
-				confidence: confidenceBucket(ranked[0]?.relevance),
-				elapsedMs,
-				...(judged > 0 ? {} : { reason: failure ?? "missing" }),
-			});
-			return text(
-				renderFindResults({ ranked, total, judged, limit, model: config.model, elapsedMs, failure }),
-				// Shape only, like ask_jev: details persist in the session.
-				{ candidates: candidates.length, total, judged, elapsedMs, ...(failure ? { failure } : {}) },
-			);
+			}
+			return text(result.text, result.details);
 		},
 	});