@selesai/code 0.13.37 → 0.13.39

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.39] - 2026-10-02
+
+### Changed
+- **`/tokenin usage` shows the account balance.** It queries `/tokenin/account/me/balance` and shows available credit (plan, PAYG, debt), active plan credit used, and plan expiry; a 404 falls back to the LiteLLM `/key/info` quota view.
+- **The `researcher` subagent uses `web_explore`** from the bundled `pi-web-agent` extension instead of `pi-web-access` tools; `pi-web-agent` registers a builtin-agent augmentation so foreground `researcher` children load it.
+- **Graft CLI floor raised to 0.21** (`MIN_GRAFT_VERSION` 0.21.0, install spec `@nanonets/graft@^0.21`).
+
+## [0.13.38] - 2026-10-01
+
+### Changed
+- **`jev_find` returns source evidence, not just file pointers.** Large trees are narrowed through directory, file, and source-unit judging; results include ranked files, reading leads, and accepted source verbatim with original line numbers, capped at 12 Jev requests and 16 KiB of source per call. JavaScript and TypeScript are split into declarations when the parser is available; other files and installs without it use bounded text chunks.
+
+### Fixed
+- **Jev Find remains useful when Jev cannot judge.** It returns ripgrep-ranked candidates with local keyword-window source, and provider diagnostics expose only a failure category and optional HTTP status, never raw provider error text.
+
 ## [0.13.37] - 2026-09-30
 
 ### Changed

package/dist/extensions/jev/decisions.test.ts

@@ -17,6 +17,7 @@ const state = vi.hoisted(() => ({ settingsPath: "" }));
 // layer owns the non-streaming decisions request), so a suite stubs that.
 import {
 	askJev,
+	askJevAnswers,
 	buildConversation,
 	buildJevPayload,
 	confidenceBucket,
@@ -278,6 +279,23 @@ describe("askJev", () => {
 		expect(await ask()).toMatchObject({ failure: "malformed" });
 	});
 
+	it("reports safe transport diagnostics without returning raw provider errors", async () => {
+		const error = Object.assign(new Error("secret=must-not-escape"), { status: 503 });
+		completeMock.mockRejectedValue(error);
+
+		const result = await askJevAnswers(runtime() as never, CONNECTION, { payload: {}, maxBytes: 1_024 });
+		expect(result).toMatchObject({ failure: "transport", diagnostic: { kind: "provider-error", httpStatus: 503 } });
+		expect(JSON.stringify(result)).not.toContain("must-not-escape");
+	});
+
+	it("extracts only the HTTP status from TokenIn's error completion", async () => {
+		completeMock.mockResolvedValue(jevResponse("", { stopReason: "error", errorMessage: "HTTP 429: private response body" }));
+
+		const result = await askJevAnswers(runtime() as never, CONNECTION, { payload: {}, maxBytes: 1_024 });
+		expect(result).toMatchObject({ failure: "transport", diagnostic: { kind: "provider-error", httpStatus: 429 } });
+		expect(JSON.stringify(result)).not.toContain("private response body");
+	});
+
 	it("abstains per question on an unlisted, low-confidence, or missing answer", async () => {
 		completeMock.mockResolvedValue(jevResponse(jevAnswers({ repository_context: { choice: "maybe", confidence: 1 } })));
 		expect(await ask()).toMatchObject({ choices: {}, failure: "unknown-choice" });

package/dist/extensions/jev/decisions.ts

@@ -426,10 +426,41 @@ function responseText(response: { content: readonly { type: string; text?: strin
 }
 
 function failureReason(error: unknown): JevAbstainReason {
-	if (isRecord(error) && (error.name === "TimeoutError" || error.name === "AbortError")) return "timeout";
+	try {
+		if (isRecord(error) && (error.name === "TimeoutError" || error.name === "AbortError")) return "timeout";
+	} catch {
+		// A hostile error object is still just a transport failure.
+	}
 	return "transport";
 }
 
+function failureDiagnostic(error: unknown, failure: JevAbstainReason): JevFailureDiagnostic {
+	if (failure === "timeout") return { kind: "timeout" };
+	try {
+		const response = isRecord(error) && isRecord(error.response) ? error.response : undefined;
+		const message =
+			typeof error === "string"
+				? error
+				: error instanceof Error
+					? error.message
+					: isRecord(error) && typeof error.errorMessage === "string"
+						? error.errorMessage
+						: "";
+		const messageStatus = /^HTTP (\d{3}):/.exec(message)?.[1];
+		const httpStatus =
+			(isRecord(error) ? (error.status ?? error.statusCode ?? response?.status) : undefined) ??
+			(messageStatus ? Number(messageStatus) : undefined);
+		return {
+			kind: "provider-error",
+			...(typeof httpStatus === "number" && Number.isInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599
+				? { httpStatus }
+				: {}),
+		};
+	} catch {
+		return { kind: "provider-error" };
+	}
+}
+
 interface JevAuth {
 	ok: boolean;
 	apiKey?: string;
@@ -494,10 +525,17 @@ export async function askJev(
 	return { choices, rejected, elapsedMs: result.elapsedMs };
 }
 
+/** Safe, content-free context for a failed Jev request. Never contains provider error text. */
+export interface JevFailureDiagnostic {
+	kind: "timeout" | "provider-error" | "malformed-response";
+	httpStatus?: number;
+}
+
 /** Jev's raw `answers` envelope, or why the request produced none. */
 export interface JevAnswers {
 	answers?: Record<string, unknown>;
 	failure?: JevAbstainReason;
+	diagnostic?: JevFailureDiagnostic;
 	elapsedMs: number;
 }
 
@@ -510,7 +548,8 @@ export interface JevAnswers {
  * was asked. Nothing beyond the envelope is validated here, so a caller that
  * expects typed answers owns interpreting them. Every failure — no provider
  * template, no credential, an oversized request, a timeout, a rejected call, or
- * malformed JSON — is an absent decision, and this never throws.
+ * malformed JSON — is an absent decision, and this never throws. Failure diagnostics
+ * contain only a category and optional HTTP status, never provider error text.
  */
 export async function askJevAnswers(
 	ctx: JevRuntime,
@@ -518,7 +557,11 @@ export async function askJevAnswers(
 	request: { payload: unknown; maxBytes: number },
 ): Promise<JevAnswers> {
 	const started = Date.now();
-	const abstained = (failure: JevAbstainReason): JevAnswers => ({ failure, elapsedMs: Date.now() - started });
+	const abstained = (failure: JevAbstainReason, diagnostic?: JevFailureDiagnostic): JevAnswers => ({
+		failure,
+		...(diagnostic ? { diagnostic } : {}),
+		elapsedMs: Date.now() - started,
+	});
 
 	const access = await jevAccess(ctx, connection);
 	if ("failure" in access) return abstained(access.failure);
@@ -539,16 +582,21 @@ export async function askJevAnswers(
 			{ apiKey: auth.apiKey, headers: auth.headers, maxTokens: JEV_MAX_TOKENS, signal },
 		);
 	} catch (error) {
-		return abstained(failureReason(error));
+		const failure = failureReason(error);
+		return abstained(failure, failureDiagnostic(error, failure));
 	}
 	// A provider failure or a deadline arrives as a message with an error stop
 	// reason rather than as a thrown error.
 	if (completion.stopReason === "error" || completion.stopReason === "aborted") {
-		return abstained(signal.aborted ? "timeout" : "transport");
+		const failure = signal.aborted ? "timeout" : "transport";
+		return abstained(
+			failure,
+			failure === "timeout" ? { kind: "timeout" } : failureDiagnostic(completion.errorMessage, failure),
+		);
 	}
 
 	const answers = parseAnswers(responseText(completion));
-	if (!answers) return abstained("malformed");
+	if (!answers) return abstained("malformed", { kind: "malformed-response" });
 	return { answers, elapsedMs: Date.now() - started };
 }
 

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

@@ -6,7 +6,7 @@
  * assert what the agent observes — the state Jev was sent, the answers that come
  * back, and what never leaves the process — never private helper order.
  */
-import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
@@ -32,8 +32,26 @@ vi.mock("@selesai/code", () => ({
 	}),
 }));
 
-import jevAskToolExtension, { askPath, FIND_BATCH, fitFindPayload, MAX_ASK_QUESTIONS } from "./jev-ask-tool.ts";
-import { JEV_ROUTING_EVENT, serializeJevRequest } from "./jev/decisions.ts";
+import jevAskToolExtension, {
+	askPath,
+	childDirectory,
+	FIND_BATCH,
+	FIND_MAX_REQUESTS,
+	FIND_MAX_SOURCE_BYTES,
+	FindRequests,
+	fitJudgePayloads,
+	MAX_ASK_QUESTIONS,
+	renderSourceBlocks,
+	runJevFind,
+	unitView,
+} from "./jev-ask-tool.ts";
+import { chunkUnits, loadTypeScript, splitSourceUnits } from "./jev-find-source.ts";
+import {
+	JEV_ROUTING_EVENT,
+	type JevAbstainReason,
+	type JevFailureDiagnostic,
+	serializeJevRequest,
+} from "./jev/decisions.ts";
 import { jevResponse, providerTemplate } from "./jev/test-support.ts";
 
 const FILE_SENTINEL = "FILE_BODY_MUST_RETURN_TO_JE ONLY";
@@ -425,14 +443,346 @@ describe("jev_find", () => {
 		return { text: result.content[0]?.text ?? "", details: result.details };
 	};
 
+	type Stage = "directories" | "files" | "units";
+	/**
+	 * A fake Jev for `runJevFind`: it reads each request the way Jev would (state keyed by stage,
+	 * one noul per quoted key) and answers with `decide`, refusing an oversized request exactly as
+	 * the real transport does. `fail` scripts whole-request failures by stage and attempt.
+	 */
+	function fakeJev(
+		decide: (stage: Stage, key: string) => number | undefined,
+		options: {
+			maxBytes?: number;
+			fail?: (stage: Stage, attempt: number) => JevAbstainReason | undefined;
+			diagnostic?: JevFailureDiagnostic;
+		} = {},
+	) {
+		const calls: Array<{ stage: Stage; keys: string[]; bytes: number; payload: Record<string, unknown> }> = [];
+		const ask = async (payload: Record<string, unknown>) => {
+			const state = payload.state as Record<string, unknown>;
+			const stage = (["directories", "files", "units"] as const).find((key) => key in state) as Stage;
+			const questions = payload.questions as Record<string, { instructions: { question: string } }>;
+			const keys = Object.values(questions).map((q) => /"([^"]+)"/.exec(q.instructions.question)?.[1] ?? "");
+			const bytes = Buffer.byteLength(JSON.stringify(payload), "utf-8");
+			calls.push({ stage, keys, bytes, payload });
+			if (serializeJevRequest(payload, options.maxBytes ?? 32 * 1024) === undefined) {
+				return { failure: "overflow" as const, elapsedMs: 0 };
+			}
+			const failure = options.fail?.(stage, calls.filter((call) => call.stage === stage).length);
+			if (failure) return { failure, ...(options.diagnostic ? { diagnostic: options.diagnostic } : {}), elapsedMs: 1 };
+			const answers: Record<string, unknown> = {};
+			Object.keys(questions).forEach((name, index) => {
+				const noul = decide(stage, keys[index]);
+				if (noul !== undefined) answers[name] = { noul };
+			});
+			return { answers, elapsedMs: 1 };
+		};
+		return { ask, calls, keys: (stage: Stage) => calls.filter((call) => call.stage === stage).flatMap((call) => call.keys) };
+	}
+
+	let tree: string;
+	const RETRY_SOURCE = [
+		'import { x } from "./x";',
+		"",
+		"/** Doubles the delay on every retry. */",
+		"export function retryBackoff(attempt: number) {",
+		"\treturn 100 * 2 ** attempt;",
+		"}",
+		"",
+		"export const unrelated = x; // not the retry path",
+		"",
+	].join("\n");
+
 	beforeAll(() => {
 		writeFileSync(join(repo, "src", "other.ts"), "// mentions round only in passing\nexport const x = 1;\n", "utf-8");
 		writeFileSync(join(repo, ".env"), "round=SECRET_ENV_VALUE\n", "utf-8");
+		// 86 files: alpha/ (30), beta/core/ (30), beta/extra/ (25), and README.md at the root.
+		tree = join(root, "tree");
+		for (const [dir, count] of [["alpha", 30], ["beta/core", 30], ["beta/extra", 25]] as const) {
+			mkdirSync(join(tree, dir), { recursive: true });
+			for (let i = 0; i < count; i += 1) writeFileSync(join(tree, dir, `f${i}.ts`), `export const v${i} = ${i};\n`, "utf-8");
+		}
+		writeFileSync(join(tree, "beta/core/f3.ts"), RETRY_SOURCE, "utf-8");
+		writeFileSync(join(tree, "README.md"), "# Tree\n\nA fixture.\n", "utf-8");
+	});
+
+	const QUESTION = "how is the retry backoff computed";
+	const TREE_VERDICTS = (stage: Stage, key: string): number | undefined => {
+		if (stage === "directories") return ({ "alpha/": 0.1, "beta/": 0.9, "beta/core/": 0.8, "beta/extra/": 0.2 } as Record<string, number>)[key];
+		if (stage === "files") return key === "beta/core/f3.ts" ? 0.95 : 0.05;
+		return key.includes("retryBackoff") ? 0.9 : 0.1;
+	};
+
+	describe("directory descent", () => {
+		it("prunes a rejected directory and recurses into a kept one, judging root files alongside", async () => {
+			const jev = fakeJev(TREE_VERDICTS);
+			const result = await runJevFind({ rg: "rg", cwd: tree, root: ".", question: QUESTION, maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			expect(jev.keys("directories")).toEqual(["beta/", "alpha/", "beta/core/", "beta/extra/"]);
+			// The kept directory is described by its most promising files and keyword hits.
+			const betaState = (jev.calls[0].payload.state as { directories: Record<string, string> }).directories["beta/"];
+			expect(betaState).toMatch(/^55 file\(s\): core\/f3\.ts/);
+			expect(betaState).toContain("Keyword hits:\ncore/f3.ts L3: /** Doubles the delay on every retry. */");
+			const judgedFiles = jev.keys("files");
+			expect(judgedFiles).toHaveLength(31);
+			expect(judgedFiles).toContain("README.md");
+			expect(judgedFiles.some((path) => path.startsWith("alpha/") || path.startsWith("beta/extra/"))).toBe(false);
+
+			expect(result.text).toMatch(/^jev_find: 1 relevant file\(s\) \(judged 31 of 86 candidates via jev-test in \d+ms\)$/m);
+			expect(result.text).toContain("Jev ruled out 2 directories holding 55 file(s).");
+			expect(result.text).toContain("- beta/core/f3.ts (0.95) — reading leads: retryBackoff lines 3-6");
+			expect(result.text.trimEnd().endsWith("End context.")).toBe(true);
+			expect(result.details).toMatchObject({ total: 86, judged: 31, relevant: 1 });
+		});
+
+		it("keeps directories whose question failed, as unknown rather than rejected", async () => {
+			const jev = fakeJev(TREE_VERDICTS, { fail: (stage) => (stage === "directories" ? "timeout" : undefined) });
+			const result = await runJevFind({ rg: "rg", cwd: tree, root: ".", question: QUESTION, maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			const judgedFiles = jev.keys("files");
+			expect(judgedFiles).toHaveLength(86);
+			expect(judgedFiles).toContain("alpha/f0.ts");
+			expect(result.text).not.toContain("ruled out");
+			expect(result.text).toMatch(/directories were kept unjudged \(timeout\)/);
+			expect(result.text).toContain('Source block "beta/core/f3.ts" lines 3-6:');
+		});
+
+		it("stops free descent at the directory depth limit", async () => {
+			const deepTree = join(root, "deep-tree");
+			for (const branch of ["one", "two"]) {
+				const dir = join(deepTree, "a", "b", "c", "d", "e", branch);
+				mkdirSync(dir, { recursive: true });
+				for (let i = 0; i < 30; i += 1) writeFileSync(join(dir, `backoff${i}.ts`), `export const backoff${i} = ${i};\n`, "utf-8");
+			}
+			const jev = fakeJev(() => 0.9);
+			const result = await runJevFind({
+				rg: "rg",
+				cwd: deepTree,
+				root: ".",
+				question: "backoff",
+				maxBytes: 32 * 1024,
+				model: "jev-test",
+				ask: jev.ask,
+			});
+
+			expect(jev.keys("directories")).toEqual([]);
+			expect(jev.keys("files")).toHaveLength(60);
+			expect(result.details.requests).toBeLessThanOrEqual(FIND_MAX_REQUESTS);
+		});
+
+		it("names the next directory level below a root", () => {
+			expect(childDirectory("src/a/b.ts", ".")).toBe("src");
+			expect(childDirectory("src/a/b.ts", "src")).toBe("src/a");
+			expect(childDirectory("src/b.ts", "src")).toBeUndefined();
+		});
+	});
+
+	describe("source units", () => {
+		it("splits TypeScript into statements, merged imports, and class members that keep their header", async () => {
+			const ts = await loadTypeScript();
+			expect(ts).toBeDefined();
+			const filler = Array.from({ length: 40 }, (_, i) => `\t\tconst step${i} = ${i};`);
+			const text = [
+				'import { a } from "a";', // 1
+				'import { b } from "b";', // 2
+				"", // 3
+				"// ---- section banner ----", // 4
+				"", // 5
+				"/** Adds one. */", // 6
+				"export function add(x: number) {", // 7
+				"\treturn x + a + b;", // 8
+				"}", // 9
+				"", // 10
+				"export class Big {", // 11
+				"\t/** The first step. */", // 12
+				"\tfirst() {", // 13
+				...filler, // 14-53
+				"\t}", // 54
+				"\tsecond() { return 2; } // trailing note", // 55
+				"}", // 56
+				"",
+			].join("\n");
+			expect(splitSourceUnits("x.ts", text, ts)).toEqual([
+				{ name: "imports", start: 1, end: 2 },
+				{ name: "add", start: 6, end: 9 },
+				{ name: "Big.first", start: 12, end: 54, header: 11 },
+				{ name: "Big.second", start: 55, end: 55, header: 11 },
+			]);
+		});
+
+		it("chunks other files, and scripts when TypeScript is missing, by blank lines into at most 40 lines", () => {
+			const long = Array.from({ length: 45 }, (_, i) => `line ${i}`);
+			const text = ["# Title", "intro", "", "## Setup", "run it", "", ...long, ""].join("\n");
+			expect(splitSourceUnits("README.md", text, undefined)).toEqual([
+				{ name: "# Title", start: 1, end: 5 },
+				{ name: "line 0", start: 7, end: 46 },
+				{ name: "line 40", start: 47, end: 51 },
+			]);
+			expect(splitSourceUnits("x.ts", RETRY_SOURCE, undefined)).toEqual(chunkUnits(RETRY_SOURCE));
+		});
+
+		it("returns accepted units verbatim with their own line numbers", async () => {
+			const jev = fakeJev(TREE_VERDICTS);
+			const result = await runJevFind({
+				rg: "rg",
+				cwd: tree,
+				root: "beta/core",
+				question: QUESTION,
+				maxBytes: 32 * 1024,
+				model: "jev-test",
+				ask: jev.ask,
+			});
+			const block = result.text.split('Source block "beta/core/f3.ts" lines 3-6:\n')[1]?.split("\n").slice(0, 4);
+			expect(block).toEqual(RETRY_SOURCE.split("\n").slice(2, 6).map((line, i) => `${i + 3}: ${line}`));
+			// Only the unit Jev accepted is returned; the rejected one is not.
+			expect(jev.keys("units")).toContain("beta/core/f3.ts lines 8-8 (unrelated)");
+			expect(result.text).not.toContain("8: export const unrelated");
+		});
+
+		it("falls back to the matching source unit when Jev cannot judge the units", async () => {
+			const jev = fakeJev(TREE_VERDICTS, { fail: (stage) => (stage === "units" ? "timeout" : undefined) });
+			const result = await runJevFind({ rg: "rg", cwd: tree, root: "beta/core", question: QUESTION, maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			expect(result.text).toContain("- beta/core/f3.ts (0.95) — reading leads: retryBackoff lines 3-6");
+			expect(result.text).toContain("Jev did not judge the source units of 1 file(s) (timeout); matching source units or keyword windows are shown instead.");
+			expect(result.text).toContain('Source block "beta/core/f3.ts" lines 3-6:\n3: /** Doubles the delay on every retry. */');
+			expect(result.text).not.toContain("1: import { x }");
+		});
+
+		it("keeps the returned source within the output budget", async () => {
+			const big = join(root, "big");
+			mkdirSync(big, { recursive: true });
+			const fn = (n: number) => [
+				`export function retry${n}() {`,
+				...Array.from({ length: 58 }, (_, i) => `\tconst backoff${i} = "${"x".repeat(60)}";`),
+				"}",
+				"",
+			];
+			writeFileSync(join(big, "big.ts"), Array.from({ length: 8 }, (_, n) => fn(n)).flat().join("\n"), "utf-8");
+			const jev = fakeJev(() => 0.9);
+			const result = await runJevFind({ rg: "rg", cwd: big, root: ".", question: QUESTION, maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			expect(result.details.sourceBytes).toBeLessThanOrEqual(FIND_MAX_SOURCE_BYTES);
+			expect(result.details.sourceBytes).toBeGreaterThan(FIND_MAX_SOURCE_BYTES / 2);
+			expect(result.text).toMatch(/source block\(s\) left out to stay within 16 KB/);
+			// Every numbered line is the file's own line under its own number.
+			const rows = readFileSync(join(big, "big.ts"), "utf-8").split("\n");
+			for (const match of result.text.matchAll(/^(\d+): (.*)$/gm)) expect(rows[Number(match[1]) - 1]).toBe(match[2]);
+		});
+
+		it("clips a block to the byte budget and leaves out one that cannot show three lines", () => {
+			const rows = Array.from({ length: 20 }, (_, i) => `row ${i + 1}`);
+			const unit = { name: "u", start: 1, end: 20 };
+			const rendered = renderSourceBlocks(
+				[
+					{ path: "a.txt", unit, view: unitView(unit, undefined), rows },
+					{ path: "b.txt", unit, view: unitView(unit, undefined), rows },
+				],
+				60,
+			);
+			expect(rendered.bytes).toBeLessThanOrEqual(60);
+			expect(rendered.lines).toEqual(['', 'Source block "a.txt" lines 1-20:', "1: row 1", "2: row 2", "3: row 3", "4: row 4", "5: row 5", "6: row 6", "…"]);
+			expect(rendered.omitted).toBe(1);
+		});
+
+		it("shows a long unit around its best keyword line", () => {
+			expect(unitView({ name: "f", start: 10, end: 200 }, 150, 20)).toEqual([10, 0, ...Array.from({ length: 19 }, (_, i) => 140 + i), 0]);
+			expect(unitView({ name: "m", start: 30, end: 31, header: 5 }, undefined)).toEqual([5, 0, 30, 31]);
+		});
 	});
 
-	it("ranks ripgrep's candidates by Jev relevance and returns pointers, never contents", async () => {
+	describe("reliability", () => {
+		it("retries a transport failure once and then judges", async () => {
+			const jev = fakeJev((stage, key) => (stage === "files" ? (key.endsWith("round.ts") ? 0.9 : 0.1) : 0.9), {
+				fail: (stage, attempt) => (stage === "files" && attempt === 1 ? "transport" : undefined),
+			});
+			const result = await runJevFind({ rg: "rg", cwd: repo, root: "src", question: "rounding", maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			expect(jev.calls.filter((call) => call.stage === "files")).toHaveLength(2);
+			expect(result.details).toMatchObject({ judged: 2, retried: 1 });
+			expect(result.text).toContain("- src/round.ts (0.90)");
+		});
+
+		it("retries only once, then still returns ripgrep-ranked source", async () => {
+			const jev = fakeJev(() => 0.9, { fail: () => "transport" });
+			const result = await runJevFind({ rg: "rg", cwd: repo, root: "src", question: "rounding", maxBytes: 32 * 1024, model: "jev-test", ask: jev.ask });
+
+			expect(jev.calls).toHaveLength(2);
+			expect(result.text).toMatch(/^jev_find: Jev did not judge \(transport\); 2 candidate file\(s\), ranked by ripgrep:/);
+			expect(result.text).toContain('Source block "src/round.ts" lines 1-1:');
+		});
+
+		it("reports sanitized provider status and returns the matching source unit on transport failure", async () => {
+			const jev = fakeJev(TREE_VERDICTS, {
+				fail: () => "transport",
+				diagnostic: { kind: "provider-error", httpStatus: 503 },
+			});
+			const result = await runJevFind({
+				rg: "rg",
+				cwd: tree,
+				root: "beta/core",
+				question: QUESTION,
+				pattern: "retry",
+				maxBytes: 32 * 1024,
+				model: "jev-test",
+				ask: jev.ask,
+			});
+
+			expect(result.text).toContain("Diagnostic: Jev provider request failed (HTTP 503).");
+			expect(result.details).toMatchObject({ failure: "transport", diagnostic: { kind: "provider-error", httpStatus: 503 } });
+			expect(result.text).toContain("retryBackoff lines 3-6");
+			expect(result.text).toContain('Source block "beta/core/f3.ts" lines 3-6:\n3: /** Doubles the delay on every retry. */');
+		});
+
+		it("never sends more than the request cap", async () => {
+			const asked: number[] = [];
+			const requests = new FindRequests(async () => {
+				asked.push(1);
+				return { failure: "transport", elapsedMs: 0 };
+			}, 3);
+			const results = await requests.sendAll([{}, {}, {}, {}, {}], 5);
+			expect(asked).toHaveLength(3);
+			expect(results.slice(3)).toEqual([undefined, undefined]);
+			expect(requests.left).toBe(0);
+		});
+
+		it("fits every payload in every stage within maxBytes (the overflow regression)", async () => {
+			// The old fit gave up once snippets hit 64 bytes and sent the rest oversized: the questions, paths,
+			// and scaffolding of a full batch alone can outgrow a small budget.
+			const long = `src/${"deeply/nested/".repeat(12)}file.ts`;
+			const items = Array.from({ length: FIND_BATCH }, (_, i) => ({ key: `${long}${i}`, text: '"\n\t\\'.repeat(500), question: `Is "${long}${i}" relevant?` }));
+			const stage = { request: "q", stateKey: "files", criteria: { true: "yes", false: "no" } };
+			const fitted = fitJudgePayloads(stage, items, 4 * 1024);
+			expect(fitted.dropped).toEqual([]);
+			expect(fitted.payloads.flatMap((entry) => entry.items).sort((a, b) => a - b)).toEqual(items.map((_, i) => i));
+			for (const entry of fitted.payloads) expect(serializeJevRequest(entry.payload, 4 * 1024)).toBeDefined();
+			// An item that cannot fit alone is dropped, never sent oversized.
+			expect(fitJudgePayloads(stage, [{ key: "k", text: "", question: "x".repeat(5_000) }], 4 * 1024)).toEqual({ payloads: [], dropped: [0] });
+
+			const maxBytes = 6 * 1024;
+			const descent = fakeJev(TREE_VERDICTS, { maxBytes });
+			await runJevFind({ rg: "rg", cwd: tree, root: ".", question: `${QUESTION} ${"really ".repeat(2_000)}`, maxBytes, model: "jev-test", ask: descent.ask });
+			const units = fakeJev(TREE_VERDICTS, { maxBytes });
+			await runJevFind({ rg: "rg", cwd: tree, root: "beta/core", question: QUESTION, maxBytes, model: "jev-test", ask: units.ask });
+			const calls = [...descent.calls, ...units.calls];
+			expect(new Set(calls.map((call) => call.stage))).toEqual(new Set(["directories", "files", "units"]));
+			for (const call of calls) expect(call.bytes).toBeLessThanOrEqual(maxBytes);
+			expect(descent.calls.length).toBeLessThanOrEqual(FIND_MAX_REQUESTS);
+		});
+	});
+
+	it("registers jev_find as a finder that returns source, pointing subagents at it", () => {
+		const tool = harness().tools.jev_find;
+		expect(tool.description).toContain("verbatim");
+		expect(tool.description).not.toMatch(/never contents|pointers only/i);
+		expect(tool.description).toContain(".gitignore");
+		expect(tool.promptSnippet).toContain("source");
+		expect(tool.promptGuidelines?.join("\n")).toContain("subagent");
+	});
+
+	it("ranks files, returns the accepted source verbatim, and never sends secret files", async () => {
 		const session = harness();
-		// Jev: the file whose question names round.ts is relevant, the rest are not.
+		// Jev: anything naming round.ts is relevant, the rest are not.
 		session.complete.mockImplementation(async (_model: unknown, request: { messages: Array<{ content: string }> }) => {
 			const sent = JSON.parse(request.messages[0].content) as { questions: Record<string, { instructions: { question: string } }> };
 			const answers = Object.fromEntries(
@@ -442,33 +792,29 @@ describe("jev_find", () => {
 		});
 		const result = await find(session, { question: "where is rounding implemented", pattern: "round", ignoreCase: true });
 
-		expect(result.text).toMatch(/judged 2 of 2 candidate/);
-		expect(result.text).toContain("- src/round.ts:1 (0.93)");
-		expect(result.text).not.toContain("other.ts");
-		expect(result.text).not.toContain(FILE_SENTINEL);
-		const sent = session.sent() as { state: { files: Record<string, string> } };
-		expect(Object.keys(sent.state.files).sort()).toEqual(["src/other.ts", "src/round.ts"]);
-		expect(sent.state.files["src/round.ts"]).toContain(FILE_SENTINEL);
-		expect(JSON.stringify(sent)).not.toContain("SECRET_ENV_VALUE");
+		expect(result.text).toMatch(/^jev_find: 1 relevant file\(s\) \(judged 2 of 2 candidates via jev-1\.13 in \d+ms\)/);
+		// The sentinel line is not valid TypeScript; the parser recovers and still names the declaration.
+		expect(result.text).toMatch(/^- src\/round\.ts \(0\.93\) — reading leads: round\b.* lines 1-1$/m);
+		expect(result.text).toContain(`Source block "src/round.ts" lines 1-1:\n1: export const round = () => ${FILE_SENTINEL};`);
+		expect(result.text).not.toContain("- src/other.ts");
+		const everything = JSON.stringify(session.complete.mock.calls);
+		expect(everything).toContain("src/other.ts");
+		expect(everything).not.toContain("SECRET_ENV_VALUE");
+		expect(session.telemetry.at(-1)).toMatchObject({ route: "find", outcome: "jev" });
 	});
 
-	it("lists a directory by glob and still returns candidates when Jev is unreachable", async () => {
+	it("still returns ripgrep-ranked files and their source when Jev is unreachable", async () => {
 		const session = harness({ credential: false });
 		const result = await find(session, { question: "rounding", path: "src", glob: "*.ts" });
 
 		expect(session.complete).not.toHaveBeenCalled();
-		expect(result.text).toMatch(/Jev did not judge \(no-credential\); 2 candidate/);
+		const lines = result.text.split("\n");
+		expect(lines[0]).toBe("jev_find: Jev did not judge (no-credential); 2 candidate file(s), ranked by ripgrep:");
 		// The question word in the path orders the unjudged listing.
-		expect(result.text.split("\n")[1]).toBe("- src/round.ts");
-	});
-
-	it("shrinks escape-heavy snippets until a full batch fits the request budget", () => {
-		// Quotes and newlines double under JSON escaping, which is what overflowed live.
-		const snippet = '"\n\t\\'.repeat(1_000);
-		const batch = Array.from({ length: FIND_BATCH }, (_, i) => ({ path: `src/f${i}.ts`, lines: [], snippet }));
-		const payload = fitFindPayload("q", batch, 32 * 1024);
-		expect(serializeJevRequest(payload, 32 * 1024)).toBeDefined();
-		expect(Object.keys(payload.questions as object)).toHaveLength(FIND_BATCH);
+		expect(lines[1]).toBe("- src/round.ts — file head lines 1-1");
+		expect(result.text).toContain(`Source block "src/round.ts" lines 1-1:\n1: export const round = () => ${FILE_SENTINEL};`);
+		expect(result.text.trimEnd().endsWith("End context.")).toBe(true);
+		expect(session.telemetry.at(-1)).toMatchObject({ route: "find", outcome: "fallback", reason: "no-credential" });
 	});
 
 	it("refuses a search root outside the working directory", async () => {