@effect-agent/pr-review 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/{github-5TCFrxfX.mjs → github-mmanX6hk.mjs}

@@ -1,5 +1,5 @@
 import { Context, DateTime, Effect, Encoding, Layer, Option, Redacted, Result, Schema } from "effect";
-import { Agent, AgentPolicy, Subagent, SubagentPolicy, SubagentRuntime, ToolExecutionClass } from "effect-agent";
+import { Agent, AgentPolicy, Subagent, SubagentPolicy, SubagentRuntime, ToolExecutionClass, ToolResultBounds } from "effect-agent";
 import { Tool, Toolkit } from "effect/unstable/ai";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 //#region src/internal/diff.ts
@@ -24,8 +24,57 @@ var ChangedFile = class extends Schema.Class("@effect-agent/pr-review/ChangedFil
 	/** Present for renames/copies: the path the file previously had. */
 	previousPath: Schema.optionalKey(ChangedPath),
 	/** Unified-diff hunks; absent for binary or oversized files. */
-	patch: Schema.optionalKey(Schema.String)
+	patch: Schema.optionalKey(Schema.String),
+	/**
+	* Bounded UTF-8 content used only when the provider omitted `patch`.
+	* Modified files require both sides; additions require head content and
+	* deletions require base content. These values are review evidence, never
+	* GitHub inline-comment anchors.
+	*/
+	reviewBaseContent: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(2e5))),
+	reviewHeadContent: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(2e5)))
 }) {};
+/** Complete rendered fallback evidence must fit one ordinary model context. */
+const MAX_REVIEW_CONTENT_CHARS = 22e4;
+/**
+* Render complete patchless evidence, or refuse it when a required side is
+* absent or B/H annotation would exceed the model-facing bound. Callers use
+* this same value for planning and tool output so truncated fallback evidence
+* can never count as complete coverage.
+*/
+const renderReviewContent = (file) => {
+	if (file.patch !== void 0) return void 0;
+	const includeBase = file.status !== "added";
+	const includeHead = file.status !== "removed";
+	const sections = ["[GitHub omitted the unified diff. B/H lines below are bounded full-file review content, not valid inline-comment anchors. Report defects from this evidence as non-anchored concerns.]"];
+	let renderedLength = sections[0]?.length ?? 0;
+	const append = (part) => {
+		const nextLength = renderedLength + 1 + part.length;
+		if (nextLength > 22e4) return false;
+		sections.push(part);
+		renderedLength = nextLength;
+		return true;
+	};
+	const appendSide = (side, header, content) => {
+		if (!append(header)) return false;
+		const lines = content.split("\n");
+		for (let index = 0; index < lines.length; index += 1) if (!append(`${side}${index + 1}   ${lines[index] ?? ""}`)) return false;
+		return true;
+	};
+	if (includeBase) {
+		if (file.reviewBaseContent === void 0) return void 0;
+		if (!appendSide("B", "[BASE VERSION]", file.reviewBaseContent)) return void 0;
+	}
+	if (includeHead) {
+		if (file.reviewHeadContent === void 0) return void 0;
+		if (!appendSide("H", "[HEAD VERSION]", file.reviewHeadContent)) return void 0;
+	}
+	return sections.join("\n");
+};
+/** Whether complete patchless evidence fits the model-facing review bound. */
+const hasReviewableContent = (file) => renderReviewContent(file) !== void 0;
+/** Whether the reviewer has either a real patch or bounded textual fallback evidence. */
+const isReviewableFile = (file) => file.patch !== void 0 || hasReviewableContent(file);
 const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
 /**
 * Parse unified-diff hunk text into coordinate-tagged lines. Lines outside a
@@ -188,6 +237,8 @@ const MAX_FINDINGS = 20;
 const MAX_CONCERNS = 10;
 /** Annotated patches larger than this are truncated with an explicit marker. */
 const MAX_PATCH_CHARS = 6e4;
+/** The encoded Tool result must retain one complete bounded content fallback. */
+const REVIEW_TOOL_RESULT_MAX_BYTES = 2 * 1024 * 1024;
 /** One `read_file` slice never exceeds this many lines. */
 const MAX_SLICE_LINES = 1e3;
 const DEFAULT_SLICE_LINES = 400;
@@ -196,7 +247,9 @@ var ChangedFileSummary = class extends Schema.Class("@effect-agent/pr-review/Cha
 	status: ChangedFileStatus,
 	additions: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
 	deletions: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
-	hasTextualDiff: Schema.Boolean
+	hasTextualDiff: Schema.Boolean,
+	/** True when a missing patch was recovered as bounded UTF-8 base/head content. */
+	hasReviewableContent: Schema.Boolean
 }) {};
 var ChangedFilesView = class extends Schema.Class("@effect-agent/pr-review/ChangedFilesView")({
 	totalFiles: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
@@ -219,16 +272,23 @@ var FileDiffQuery = class extends Schema.Class("@effect-agent/pr-review/FileDiff
 var FileDiffView = class extends Schema.Class("@effect-agent/pr-review/FileDiffView")({
 	path: ChangedPath,
 	status: ChangedFileStatus,
+	reviewMode: Schema.Literals([
+		"diff",
+		"content",
+		"unavailable"
+	]),
 	/**
 	* The unified diff with explicit RIGHT-side line numbers: `R<n>` marks a
 	* line present in the new file version (only those may anchor findings);
-	* `-` marks removed lines. Empty when no textual diff exists.
+	* `-` marks removed lines. For content fallback, `B<n>` and `H<n>`
+	* identify base/head lines for reading only; they are never valid anchors.
+	* Empty only when neither a patch nor bounded textual content exists.
 	*/
 	annotatedPatch: Schema.String,
 	truncated: Schema.Boolean
 }) {};
 const ReadFileDiff = Tool.make("read_file_diff", {
-	description: "Read the annotated unified diff of one changed file. Lines marked R<number> exist in the new version and are the only valid finding anchors.",
+	description: "Read one changed file's review evidence. A normal unified diff marks valid anchors as R<number>. When GitHub omitted the diff, bounded base/head content is returned with B/H line labels for review but no valid inline anchors.",
 	parameters: FileDiffQuery,
 	success: FileDiffView,
 	failure: Schema.Union([PullRequestSourceFailure, ReviewInputViolation]),
@@ -275,7 +335,8 @@ const listChangedFilesHandler = (_query) => Effect.gen(function* () {
 			status: file.status,
 			additions: file.additions,
 			deletions: file.deletions,
-			hasTextualDiff: file.patch !== void 0
+			hasTextualDiff: file.patch !== void 0,
+			hasReviewableContent: hasReviewableContent(file)
 		}))
 	});
 });
@@ -291,11 +352,14 @@ const readFileDiffHandler = (query) => Effect.gen(function* () {
 		input: relative,
 		reason: "Path is not part of this pull request's changeset."
 	});
-	const annotated = file.patch === void 0 ? "" : annotatePatch(file.patch);
-	const truncated = annotated.length > MAX_PATCH_CHARS;
+	const contentEvidence = renderReviewContent(file);
+	const reviewMode = file.patch !== void 0 ? "diff" : contentEvidence !== void 0 ? "content" : "unavailable";
+	const annotated = file.patch === void 0 ? contentEvidence ?? "" : annotatePatch(file.patch);
+	const truncated = reviewMode === "diff" && annotated.length > MAX_PATCH_CHARS;
 	return FileDiffView.make({
 		path: file.path,
 		status: file.status,
+		reviewMode,
 		annotatedPatch: truncated ? `${annotated.slice(0, MAX_PATCH_CHARS)}\n[diff truncated]` : annotated,
 		truncated
 	});
@@ -343,12 +407,30 @@ const FindingSeverity = Schema.Literals([
 	"important",
 	"nit"
 ]);
+/**
+* What kind of problem a finding names. Model-claimed like severity — it is a
+* label for scanning a busy review, never an input to the check conclusion.
+*/
+const FindingCategory = Schema.Literals([
+	"correctness",
+	"security",
+	"concurrency",
+	"performance",
+	"resources",
+	"error-handling",
+	"testing",
+	"maintainability",
+	"style",
+	"docs"
+]);
 var ReviewFinding = class extends Schema.Class("@effect-agent/pr-review/ReviewFinding")({
 	path: ChangedPath,
 	/** 1-based line numbers in the NEW file version; must appear in the diff. */
 	startLine: Schema.Int.check(Schema.isGreaterThan(0)),
 	endLine: Schema.Int.check(Schema.isGreaterThan(0)),
 	severity: FindingSeverity,
+	/** Optional problem-kind label rendered next to the severity. */
+	category: Schema.optionalKey(FindingCategory),
 	title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
 	body: Schema.NonEmptyString.check(Schema.isMaxLength(2e3)),
 	/** Replacement for exactly lines startLine..endLine; omit when unsure. */
@@ -371,12 +453,26 @@ var ReviewConcern = class extends Schema.Class("@effect-agent/pr-review/ReviewCo
 	title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
 	body: Schema.NonEmptyString.check(Schema.isMaxLength(2e3))
 }) {};
+/** The per-entry walkthrough summary bound, and the entries bound (the changeset cap). */
+const MAX_WALKTHROUGH_SUMMARY_CHARS = 240;
+const MAX_WALKTHROUGH_ENTRIES = 300;
+/**
+* One reviewed file's one-sentence change summary. Rendered only when the
+* path is actually part of the changeset — like finding anchors, walkthrough
+* paths are validated host-side and invented ones are dropped.
+*/
+var WalkthroughEntry = class extends Schema.Class("@effect-agent/pr-review/WalkthroughEntry")({
+	path: ChangedPath,
+	summary: Schema.NonEmptyString.check(Schema.isMaxLength(240))
+}) {};
 var CodeReview = class extends Schema.Class("@effect-agent/pr-review/CodeReview")({
 	summary: Schema.NonEmptyString.check(Schema.isMaxLength(4e3)),
 	verdict: ReviewVerdict,
 	findings: Schema.Array(ReviewFinding).check(Schema.isMaxLength(20)),
 	/** Non-anchorable concerns; absent when the review raises none. */
-	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(10)))
+	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(10))),
+	/** Per-file change summaries; absent when the model provides none. */
+	walkthrough: Schema.optionalKey(Schema.Array(WalkthroughEntry).check(Schema.isMaxLength(300)))
 }) {};
 const resolveGuidance = (guidance, mission) => {
 	if (guidance === void 0) return [];
@@ -393,15 +489,16 @@ const makeReviewInstructions = (options = {}) => (mission) => {
 		mission.body.length > 0 ? `Author description:\n${mission.body}` : "The author provided no description.",
 		...resolveGuidance(options.guidance, mission),
 		"Work in this order:",
-		"1. Call list_changed_files once to see the changeset.",
-		"2. Call read_file_diff for every file you review. In its output, only lines marked R<number> exist in the new version; those numbers are the only valid values for startLine and endLine. Never anchor a finding to a removed (-) line.",
-		"3. Call read_file when you need surrounding context the diff does not show. ONLY files in the changeset are readable: a request for any other path (an import, a neighbor, a config) returns a failed result — do not retry it; reason from the diff instead and note the gap honestly in your summary when it matters.",
+		"1. Call list_changed_files once to see the changeset. That list is your COMPLETE review scope: in incremental reviews it is deliberately a subset of the pull request's full diff (totalFiles counts the whole pull request), and everything it omits was already reviewed or excluded.",
+		"2. Call read_file_diff for every file you review. A normal diff marks new-version anchors as R<number>; only those numbers are valid startLine/endLine values. When GitHub omitted a diff, the tool may return bounded base/head content marked B/H instead. Review that content, but report its defects as non-anchored concerns because B/H lines cannot anchor GitHub comments. Never anchor a finding to a removed (-), B, or H line.",
+		"3. Call read_file when you need surrounding context the diff does not show. ONLY listed files are readable — read_file_diff and read_file both return a failed result for any other path (an import, a neighbor, a file named in the description). Do not request or retry unlisted paths; reason from the visible diffs instead and note the gap honestly in your summary when it matters.",
 		"4. Review for real defects first: correctness, security, concurrency, resource leaks, error handling, API misuse. Style nits are least important. Do not praise; do not restate the diff.",
 		"When the diff adds or changes a test, check that it can actually fail: a test that would still pass with the bug present is theatre, not coverage. The usual tell is a loose assertion standing where an exact one belongs — >= or a truthiness check over an expected value, or a snapshot that absorbs whatever it is handed.",
 		"Go shallow only when the diff has no behavioral surface at all: doc typos, formatting, lockfile or generated-code regeneration, a mechanical rename. Line count is not the signal — a one-line change to auth, money, SQL, a comparison operator, or a config default is not trivial.",
 		"Drop bloat-shaped findings before reporting: defensive checks for cases that cannot happen, abstractions used once, comments restating obvious code, tests asserting tautologies, just-in-case guards. A finding must be sound, correct, and worth acting on; prefer an explicit keep over an invented finding.",
 		"5. After collecting anchored findings, deliberately scan for concerns with NO line to point at: deletion or cleanup plans for code the diff replaces, rollout or migration sequencing, coverage gaps the diff implies but does not add, scope questions only the author can answer. Report each as a \"concern\", never as a finding with an invented anchor; report none when none exist.",
-		"6. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {\"summary\": <string, 1-3 paragraphs of overall assessment>, \"verdict\": <\"approve\" | \"comment\" | \"request-changes\">, \"findings\": [{\"path\": <string, a changed file path>, \"startLine\": <integer, an R-marked new-file line>, \"endLine\": <integer, >= startLine, same file, R-marked>, \"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string, why it matters and what to do>, \"suggestion\": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], \"concerns\": <array, OPTIONAL: [{\"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string>}], only for step-5 concerns with no valid anchor — never duplicate a finding here>}.",
+		`6. Write a walkthrough: for every file you reviewed, one factual sentence (<= 240 chars) describing what changed in that file — written for a reader scanning the pull request, never restating the diff line by line. Use only paths from list_changed_files; invented paths are dropped.`,
+		"7. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {\"summary\": <string, 1-3 paragraphs of overall assessment>, \"verdict\": <\"approve\" | \"comment\" | \"request-changes\">, \"findings\": [{\"path\": <string, a changed file path>, \"startLine\": <integer, an R-marked new-file line>, \"endLine\": <integer, >= startLine, same file, R-marked>, \"severity\": <\"blocking\" | \"important\" | \"nit\">, \"category\": <OPTIONAL: \"correctness\" | \"security\" | \"concurrency\" | \"performance\" | \"resources\" | \"error-handling\" | \"testing\" | \"maintainability\" | \"style\" | \"docs\">, \"title\": <string, <= 120 chars>, \"body\": <string, why it matters and what to do>, \"suggestion\": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], \"concerns\": <array, OPTIONAL: [{\"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string>}], only for step-5 concerns with no valid anchor — never duplicate a finding here>, \"walkthrough\": <array, OPTIONAL: [{\"path\": <string, a changed file path>, \"summary\": <string, the step-6 sentence>}], one entry per reviewed file>}.",
 		`Report at most ${maxFindings} findings and at most 10 concerns; prefer the most important ones. An empty findings array with verdict "approve" is a valid review. Include "suggestion" only when you are confident the replacement compiles and preserves intent; its text must contain the full replacement for every line in the range and nothing else.`,
 		"Use verdict \"request-changes\" only when at least one finding or concern is \"blocking\". Line anchors you invent will be discarded, so copy R-numbers from read_file_diff output."
 	].join("\n");
@@ -414,8 +511,10 @@ const defaultReviewPolicy = AgentPolicy.make({
 	maxToolCalls: 24,
 	maxDuration: "8 minutes",
 	toolConcurrency: 2,
+	repeatedFailureLimit: 12,
 	tokenBudget: 3e5,
 	contextTokenLimit: 15e4,
+	toolResultBounds: ToolResultBounds.make({ maxBytes: REVIEW_TOOL_RESULT_MAX_BYTES }),
 	onExhaustion: "final-answer"
 });
 const PullRequestReviewer = Agent.define("pr-reviewer", {
@@ -456,7 +555,7 @@ var ReviewUnitPlan = class extends Schema.Class("@effect-agent/pr-review/ReviewU
 	/** True when the source returned fewer files than the pull request has. */
 	truncated: Schema.Boolean,
 	units: Schema.Array(ReviewUnit).check(Schema.isMaxLength(8)),
-	/** Changed files without a textual diff; no finding can anchor to them. */
+	/** Changed files with neither a textual diff nor bounded base/head text. */
 	undiffablePaths: Schema.Array(ChangedPath).check(Schema.isMaxLength(300)),
 	/**
 	* Diffable files beyond the fan-out capacity (MAX_REVIEW_UNITS units of
@@ -465,7 +564,11 @@ var ReviewUnitPlan = class extends Schema.Class("@effect-agent/pr-review/ReviewU
 	*/
 	unassignedPaths: Schema.Array(ChangedPath).check(Schema.isMaxLength(300))
 }) {};
-const fileCost = (file) => file.additions + file.deletions + FILE_OVERHEAD_LINES;
+const fileCost = (file) => {
+	const contentChars = (file.reviewBaseContent?.length ?? 0) + (file.reviewHeadContent?.length ?? 0);
+	const contentWeight = Math.ceil(contentChars / 200);
+	return file.additions + file.deletions + contentWeight + FILE_OVERHEAD_LINES;
+};
 const unitOf = (index, files) => ReviewUnit.make({
 	unitId: `unit-${String(index + 1).padStart(3, "0")}`,
 	paths: files.map((file) => file.path),
@@ -479,22 +582,24 @@ const unitOf = (index, files) => ReviewUnit.make({
 * then packed greedily in that order under the soft changed-line budget and
 * the hard per-unit file bound. Capacity is finite and explicit:
 *
-* - files without a textual diff are not delegated — no finding can anchor
-*   to them (anchor validation demands a parsed patch), so they surface in
-*   `undiffablePaths` instead of consuming a child's budget;
-* - diffable files beyond `MAX_REVIEW_UNITS` full units surface in
+* - files without a textual diff are still delegated when the source
+*   recovered complete bounded UTF-8 base/head content. Findings from that
+*   evidence cannot anchor inline and are reported as concerns;
+* - files with neither form of textual evidence surface in
+*   `undiffablePaths` instead of laundering missing coverage;
+* - reviewable files beyond `MAX_REVIEW_UNITS` full units surface in
 *   `unassignedPaths` so the review can report them as unreviewed, never
 *   silently truncated.
 */
 const planReviewUnits = (files, options) => {
 	const ordered = [...files].sort((left, right) => left.path < right.path ? -1 : 1);
-	const diffable = ordered.filter((file) => file.patch !== void 0);
-	const undiffable = ordered.filter((file) => file.patch === void 0);
+	const reviewable = ordered.filter(isReviewableFile);
+	const undiffable = ordered.filter((file) => !isReviewableFile(file));
 	const groups = [];
 	const unassigned = [];
 	let current = [];
 	let currentCost = 0;
-	for (const file of diffable) {
+	for (const file of reviewable) {
 		const cost = fileCost(file);
 		if (current.length >= 12 || current.length > 0 && currentCost + cost > 800) {
 			groups.push(current);
@@ -573,7 +678,9 @@ var FileReviewReport = class extends Schema.Class("@effect-agent/pr-review/FileR
 	unitId: ReviewUnitId,
 	findings: Schema.Array(ReviewFinding).check(Schema.isMaxLength(8)),
 	/** Unit-scoped concerns with no diff line to anchor to. */
-	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(3)))
+	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(3))),
+	/** One-sentence per-file change summaries for the merged walkthrough. */
+	fileSummaries: Schema.optionalKey(Schema.Array(WalkthroughEntry).check(Schema.isMaxLength(12)))
 }) {};
 const staticGuidanceLines = (guidance) => {
 	if (guidance === void 0) return [];
@@ -584,12 +691,13 @@ const makeFileReviewerInstructions = (options = {}) => (brief) => [
 	`You are a code reviewer for one unit of a pull request: unit ${brief.unitId}, covering exactly these changed files: ${brief.paths.join(", ")}. Focus: ${brief.focus}.`,
 	...staticGuidanceLines(options.guidance),
 	"Work in this order:",
-	"1. Call read_file_diff for every file in your unit. In its output, only lines marked R<number> exist in the new version; those numbers are the only valid values for startLine and endLine. Never anchor a finding to a removed (-) line.",
+	"1. Call read_file_diff for every file in your unit. A normal diff marks new-version anchors as R<number>; only those numbers are valid startLine/endLine values. When GitHub omitted a diff, the tool may return bounded base/head content marked B/H instead. Review that content, but report its defects as non-anchored concerns because B/H lines cannot anchor GitHub comments. Never anchor a finding to a removed (-), B, or H line.",
 	"2. Call read_file when you need surrounding context the diff does not show. ONLY files in the changeset are readable: a request for any other path (an import, a neighbor, a config) returns a failed result — do not retry it; reason from the diff instead and note the gap in your report when it matters.",
 	"3. Review for real defects first: correctness, security, concurrency, resource leaks, error handling, API misuse. Style nits are least important. Do not praise; do not restate the diff.",
 	"When the diff adds or changes a test, check that it can actually fail: a test that would still pass with the bug present is theatre, not coverage. The usual tell is a loose assertion standing where an exact one belongs — >= or a truthiness check over an expected value, or a snapshot that absorbs whatever it is handed.",
 	"Drop bloat-shaped findings before reporting: defensive checks for cases that cannot happen, abstractions used once, comments restating obvious code, tests asserting tautologies, just-in-case guards. A finding must be sound, correct, and worth acting on; prefer an explicit keep over an invented finding.",
-	`4. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {"unitId": ${JSON.stringify(brief.unitId)}, "findings": [{"path": <string, a file in your unit>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], "concerns": <array, OPTIONAL: [{"severity": <"blocking" | "important" | "nit">, "title": <string, <= 120 chars>, "body": <string>}], only for concerns about YOUR unit's files with no valid line anchor (a missing cleanup, a coverage gap the diff implies, sequencing the diff leaves open) — never duplicate a finding here>}.`,
+	`4. For every file in your unit, write one factual sentence (<= 240 chars) describing what changed in that file — for a reader scanning the pull request, never a line-by-line restatement.`,
+	`5. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {"unitId": ${JSON.stringify(brief.unitId)}, "findings": [{"path": <string, a file in your unit>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "category": <OPTIONAL: "correctness" | "security" | "concurrency" | "performance" | "resources" | "error-handling" | "testing" | "maintainability" | "style" | "docs">, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], "concerns": <array, OPTIONAL: [{"severity": <"blocking" | "important" | "nit">, "title": <string, <= 120 chars>, "body": <string>}], only for concerns about YOUR unit's files with no valid line anchor (a missing cleanup, a coverage gap the diff implies, sequencing the diff leaves open) — never duplicate a finding here>, "fileSummaries": <array, OPTIONAL: [{"path": <string, a file in your unit>, "summary": <string, the step-4 sentence>}], one entry per file in your unit>}.`,
 	`Report at most 8 findings and at most 3 concerns; prefer the most important ones. An empty findings array is a valid report. Never report on files outside your unit. Line anchors you invent will be discarded, so copy R-numbers from read_file_diff output.`
 ].join("\n");
 const fileReviewerInstructions = makeFileReviewerInstructions();
@@ -599,8 +707,10 @@ const defaultFileReviewerPolicy = AgentPolicy.make({
 	maxToolCalls: MAX_FILE_REVIEW_TOOL_CALLS,
 	maxDuration: "6 minutes",
 	toolConcurrency: 2,
+	repeatedFailureLimit: 12,
 	tokenBudget: 2e5,
 	contextTokenLimit: 15e4,
+	toolResultBounds: ToolResultBounds.make({ maxBytes: REVIEW_TOOL_RESULT_MAX_BYTES }),
 	onExhaustion: "fail"
 });
 /** The model-decoded delegation parameters: which unit to review. */
@@ -613,7 +723,9 @@ var FileReviewUnitResult = class extends Schema.Class("@effect-agent/pr-review/F
 	unitId: ReviewUnitId,
 	findings: Schema.Array(ReviewFinding).check(Schema.isMaxLength(8)),
 	/** Unit-scoped concerns with no diff line to anchor to. */
-	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(3)))
+	concerns: Schema.optionalKey(Schema.Array(ReviewConcern).check(Schema.isMaxLength(3))),
+	/** One-sentence per-file change summaries for the merged walkthrough. */
+	fileSummaries: Schema.optionalKey(Schema.Array(WalkthroughEntry).check(Schema.isMaxLength(12)))
 }) {};
 /**
 * One unit's review failed: the child Run ended in a typed failure (policy
@@ -680,7 +792,8 @@ const makeFanOutReviewInstructions = (options = {}) => (mission) => {
 		"3. A delegation result with \"_tag\" is a FAILED unit. Never retry it; instead your summary MUST name it honestly, e.g. \"unit-002 unreviewed: AgentPolicyError\". The plan's undiffablePaths and unassignedPaths must also be named as not reviewed when present.",
 		`4. Merge the successful units' findings: drop duplicates sharing the same path and line range keeping the most severe, rank blocking > important > nit, and keep at most ${maxFindings} findings. Drop bloat-shaped findings during the merge — defensive checks for cases that cannot happen, abstractions used once, comments restating obvious code, tests asserting tautologies; children bias toward recommending changes, and a finding must be sound, correct, and worth acting on to survive.`,
 		`5. Merge the units' concerns the same way: drop duplicates keeping the most severe, and keep at most 10.`,
-		"6. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {\"summary\": <string, 1-3 paragraphs of overall assessment, including every unreviewed unit or file>, \"verdict\": <\"approve\" | \"comment\" | \"request-changes\">, \"findings\": [{\"path\": <string>, \"startLine\": <integer>, \"endLine\": <integer>, \"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string>, \"suggestion\": <string, OPTIONAL>}], \"concerns\": <array, OPTIONAL: [{\"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string>}], the merged unit concerns>}. Copy findings and concerns verbatim from the delegation results; never invent or edit anchors.",
+		"6. Merge the units' fileSummaries into one walkthrough: copy each entry verbatim, one entry per file, dropping duplicate paths.",
+		"7. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {\"summary\": <string, 1-3 paragraphs of overall assessment, including every unreviewed unit or file>, \"verdict\": <\"approve\" | \"comment\" | \"request-changes\">, \"findings\": [{\"path\": <string>, \"startLine\": <integer>, \"endLine\": <integer>, \"severity\": <\"blocking\" | \"important\" | \"nit\">, \"category\": <string, OPTIONAL>, \"title\": <string, <= 120 chars>, \"body\": <string>, \"suggestion\": <string, OPTIONAL>}], \"concerns\": <array, OPTIONAL: [{\"severity\": <\"blocking\" | \"important\" | \"nit\">, \"title\": <string, <= 120 chars>, \"body\": <string>}], the merged unit concerns>, \"walkthrough\": <array, OPTIONAL: [{\"path\": <string>, \"summary\": <string>}], the merged fileSummaries>}. Copy findings (including \"category\" and \"suggestion\" when present), concerns, and walkthrough entries verbatim from the delegation results; never invent or edit anchors.",
 		"Use verdict \"request-changes\" only when at least one finding or concern is \"blocking\". An empty findings array with verdict \"approve\" is a valid review when every unit succeeded and found nothing."
 	].join("\n");
 };
@@ -723,7 +836,8 @@ const makeFileReviewDelegation = (child) => Subagent.define("delegate_file_revie
 	projectResult: (report) => Effect.succeed(FileReviewUnitResult.make({
 		unitId: report.unitId,
 		findings: report.findings,
-		...report.concerns !== void 0 ? { concerns: report.concerns } : {}
+		...report.concerns !== void 0 ? { concerns: report.concerns } : {},
+		...report.fileSummaries !== void 0 ? { fileSummaries: report.fileSummaries } : {}
 	})),
 	policy: fileReviewPolicy
 });
@@ -805,7 +919,7 @@ const SECTION = "";
 * Canonical changeset encoding: sorted by path so provider ordering never
 * matters, with every review-relevant field of every file.
 */
-const canonicalChangeset = (files) => files.map((file) => `${file.path}${FIELD}${file.status}${FIELD}${String(file.additions)}${FIELD}${String(file.deletions)}${FIELD}${file.patch ?? ""}`).sort().join(RECORD);
+const canonicalChangeset = (files) => files.map((file) => `${file.path}${FIELD}${file.status}${FIELD}${String(file.additions)}${FIELD}${String(file.deletions)}${FIELD}${file.patch ?? ""}${FIELD}${file.reviewBaseContent ?? ""}${FIELD}${file.reviewHeadContent ?? ""}`).sort().join(RECORD);
 /**
 * Fingerprint one review's complete input surface: the (already
 * ignore-filtered) changeset plus the caller's prompt signature — the
@@ -1068,9 +1182,21 @@ var ReviewExecutionContext = class extends Context.Service()("@effect-agent/pr-r
 const selectedPullRequestSourceLayer = (selection) => Layer.effect(PullRequestSource)(Effect.gen(function* () {
 	const source = yield* PullRequestSource;
 	const selectedPaths = new Set(selection.files.map((file) => file.path));
+	const selectedFiles = source.changedFiles.pipe(Effect.map((fullFiles) => {
+		const fullByPath = new Map(fullFiles.map((file) => [file.path, file]));
+		return selection.files.map((file) => {
+			if (file.patch !== void 0) return file;
+			const full = fullByPath.get(file.path);
+			return full === void 0 ? file : ChangedFile.make({
+				...file,
+				...full.reviewBaseContent === void 0 ? {} : { reviewBaseContent: full.reviewBaseContent },
+				...full.reviewHeadContent === void 0 ? {} : { reviewHeadContent: full.reviewHeadContent }
+			});
+		});
+	}));
 	return PullRequestSource.of({
 		metadata: source.metadata,
-		changedFiles: Effect.succeed(selection.files),
+		changedFiles: selectedFiles,
 		anchorFiles: source.anchorFiles,
 		readFile: (path) => selectedPaths.has(path) ? source.readFile(path) : Effect.fail(ReviewInputViolation.make({
 			input: path,
@@ -1140,7 +1266,7 @@ const STATE_PATTERN = /<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}
 const RETIRED_ORIGINAL_PATTERN = /<!-- effect-agent-pr-review retired-original:start -->\n([\s\S]*?)\n<!-- effect-agent-pr-review retired-original:end -->/;
 const MACHINE_COMMENT_PATTERN = new RegExp(`${REVIEW_METADATA_PATTERN.source}|${FINGERPRINT_PATTERN.source}|${STATE_PATTERN.source}`, "g");
 const VERDICT_CALLOUT_PATTERN = /^(?:> \[!(?:CAUTION|IMPORTANT)\]\n> [^\n]*(?:\n> [^\n]*)*|> (?:ℹ️|✅)[^\n]*)\n*/;
-const INLINE_FINDING_TITLE_PATTERN = /^\*\*\[(?:🛑 blocking|⚠️ important|💅 nit)\] ([^\n]+)\*\*$/;
+const INLINE_FINDING_TITLE_PATTERN = /^\*\*\[(?:🛑 blocking|⚠️ important|💅 nit)(?: · [a-z-]+)?\] ([^\n]+)\*\*$/;
 const MAX_REVIEW_BODY_CHARS = 6e4;
 /** The host-authored metadata marker is the authority gate for any edit. */
 const hasReviewMetadataMarker = (body) => /<!-- effect-agent-pr-review metadata\n/.test(body);
@@ -1437,22 +1563,60 @@ const gitHubPullRequestSourceLayer = Layer.effect(PullRequestSource)(Effect.gen(
 		return all;
 	});
 	const metadata = yield* Effect.cached(fetchMetadata.pipe(Effect.provideService(HttpClient.HttpClient, client)));
-	const changedFiles = yield* Effect.cached(fetchFiles.pipe(Effect.provideService(HttpClient.HttpClient, client)));
-	const readFile = (path) => Effect.gen(function* () {
+	const rawFiles = yield* Effect.cached(fetchFiles.pipe(Effect.provideService(HttpClient.HttpClient, client)));
+	const readRepositoryFile = (path, ref) => Effect.gen(function* () {
 		const relative = yield* normalizeRepoRelativePath(path);
-		if (!(yield* changedFiles).some((file) => file.path === relative)) return yield* ReviewInputViolation.make({
+		const encodedPath = relative.split("/").map(encodeURIComponent).join("/");
+		const buffer = yield* (yield* executeOk("readFile", withCommonHeaders(HttpClientRequest.get(`${target.apiUrl}/repos/${target.repository}/contents/${encodedPath}`).pipe(HttpClientRequest.accept("application/vnd.github.raw+json"), HttpClientRequest.setUrlParams({ ref })), target.token)).pipe(Effect.provideService(HttpClient.HttpClient, client))).arrayBuffer.pipe(Effect.mapError(failWith("readFile")));
+		if (buffer.byteLength > 2e5) return yield* ReviewInputViolation.make({
 			input: relative,
-			reason: "Path is not part of this pull request's changeset."
+			reason: `File is larger than the ${MAX_FILE_CHARS}-byte read bound.`
+		});
+		const text = yield* Effect.try({
+			try: () => new TextDecoder("utf-8", { fatal: true }).decode(buffer),
+			catch: () => ReviewInputViolation.make({
+				input: relative,
+				reason: "File is not valid UTF-8 text."
+			})
+		});
+		if (text.includes("\0")) return yield* ReviewInputViolation.make({
+			input: relative,
+			reason: "File contains binary NUL bytes."
 		});
-		const head = yield* metadata;
-		const encodedPath = relative.split("/").map(encodeURIComponent).join("/");
-		const text = yield* (yield* executeOk("readFile", withCommonHeaders(HttpClientRequest.get(`${target.apiUrl}/repos/${target.repository}/contents/${encodedPath}`).pipe(HttpClientRequest.accept("application/vnd.github.raw+json"), HttpClientRequest.setUrlParams({ ref: head.headSha })), target.token)).pipe(Effect.provideService(HttpClient.HttpClient, client))).text.pipe(Effect.mapError(failWith("readFile")));
 		if (text.length > 2e5) return yield* ReviewInputViolation.make({
 			input: relative,
 			reason: `File is larger than the ${MAX_FILE_CHARS}-character read bound.`
 		});
 		return text;
 	});
+	const changedFiles = yield* Effect.cached(Effect.gen(function* () {
+		const [files, pullRequest] = yield* Effect.all([rawFiles, metadata]);
+		return yield* Effect.forEach(files, (file) => {
+			if (file.patch !== void 0) return Effect.succeed(file);
+			const basePath = file.previousPath ?? file.path;
+			const base = file.status === "added" ? Effect.succeed(Option.none()) : readRepositoryFile(basePath, pullRequest.baseSha ?? pullRequest.baseRef).pipe(Effect.option);
+			const head = file.status === "removed" ? Effect.succeed(Option.none()) : readRepositoryFile(file.path, pullRequest.headSha).pipe(Effect.option);
+			return Effect.all({
+				base,
+				head
+			}).pipe(Effect.map(({ base, head }) => ChangedFile.make({
+				...file,
+				...Option.isSome(base) ? { reviewBaseContent: base.value } : {},
+				...Option.isSome(head) ? { reviewHeadContent: head.value } : {}
+			})));
+		}, { concurrency: 4 });
+	}));
+	const readFile = (path) => Effect.gen(function* () {
+		const relative = yield* normalizeRepoRelativePath(path);
+		const file = (yield* changedFiles).find((candidate) => candidate.path === relative);
+		if (file === void 0) return yield* ReviewInputViolation.make({
+			input: relative,
+			reason: "Path is not part of this pull request's changeset."
+		});
+		if (file.reviewHeadContent !== void 0) return file.reviewHeadContent;
+		const head = yield* metadata;
+		return yield* readRepositoryFile(relative, head.headSha);
+	});
 	return PullRequestSource.of({
 		metadata,
 		changedFiles,
@@ -1671,6 +1835,6 @@ const fingerprintUnchanged = (current) => Effect.gen(function* () {
 	return Option.isSome(latest) && latest.value === current;
 });
 //#endregion
-export { FanOutReviewToolkit as $, ReviewMission as $t, ReviewStateAuthenticator as A, ReviewUnit as At, selectedPullRequestSourceLayer as B, FileDiffView as Bt, MAX_REVIEW_STATE_MARKER_CHARS as C, parsePatch as Cn, makeFanOutReviewInstructions as Ct, ReviewScopeMode as D, MAX_MERGED_FINDINGS as Dt, ReviewMode as E, mapFileReviewChildFailure as Et, buildProfileMission as F, rankAndDedupeFindings as Ft, webCryptoReviewStateAuthenticatorLayer as G, ListChangedFilesQuery as Gt, toStoredFinding as H, FileSliceQuery as Ht, computeProfileFingerprint as I, ChangedFileSummary as It, extractFingerprint as J, PullRequestReviewer as Jt, FINGERPRINT_MARKER_LENGTH as K, MAX_CONCERNS as Kt, fromStoredConcern as L, ChangedFilesView as Lt, ReviewStateMarkerTooLarge as M, ReviewUnitPlan as Mt, StoredReviewConcern as N, UNIT_CHANGED_LINE_BUDGET as Nt, ReviewState as O, MAX_REVIEW_UNITS as Ot, StoredReviewFinding as P, planReviewUnits as Pt, FanOutCoordinatorToolkitLayer as Q, ReviewFinding as Qt, fromStoredFinding as R, CodeReview as Rt, GitCommitSha as S, commentableLines as Sn, fileReviewerInstructions as St, ReviewHeadComparison as T, makeFileReviewerInstructions as Tt, unavailableReviewStateAuthenticatorLayer as U, FindingSeverity as Ut, toStoredConcern as V, FileSlice as Vt, validateReviewState as W, ListChangedFiles as Wt, DelegateFileReview as X, ReadFileDiff as Xt, renderFingerprintMarker as Y, ReadFile as Yt, FanOutCoordinatorToolkit as Z, ReviewConcern as Zt, ReviewRetirementHost as _, normalizeRepoRelativePath as _n, fanOutHandlersLayer as _t, PriorReviews as a, listChangedFilesHandler as an, FileReviewToolkit as at, hasReviewMetadataMarker as b, ChangedPath as bn, fileReviewDelegation as bt, fingerprintUnchanged as c, readFileHandler as cn, FileReviewUnitResult as ct, gitHubReviewPublisherLayer as d, MAX_CHANGED_FILES as dn, ListReviewUnitsQuery as dt, ReviewToolkit as en, FanOutReviewer as et, gitHubReviewRetirementHostLayer as f, MAX_FILE_CHARS as fn, MAX_CHILD_CONCERNS as ft, ReviewRetirementFailure as g, ReviewInputViolation as gn, defaultFileReviewerPolicy as gt, RetirableReviewComment as h, PullRequestSourceFailure as hn, defaultFanOutPolicy as ht, PriorReviewLookupFailure as i, defaultReviewPolicy as in, FileReviewRequest as it, ReviewStateMarker as j, ReviewUnitId as jt, ReviewStateAuthenticationFailure as k, MAX_UNIT_FILES as kt, gitHubPriorReviewsLayer as l, resolveGuidance as ln, FileReviewer as lt, RetirableReview as m, PullRequestSource as mn, MAX_FILE_REVIEW_TOOL_CALLS as mt, GitHubApiFailure as n, ReviewVerdict as nn, FileReviewDelegationFailure as nt, PublishedReview as o, makeReviewInstructions as on, FileReviewToolkitLayer as ot, parseGitHubSubmittedAt as p, PullRequestMetadata as pn, MAX_CHILD_FINDINGS as pt, computeChangesetFingerprint as q, MAX_FINDINGS as qt, GitHubReviewTarget as r, clampMaxFindings as rn, FileReviewReport as rt, ReviewPublisher as s, readFileDiffHandler as sn, FileReviewUnitFailed as st, DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN as t, ReviewToolkitLayer as tn, FileReviewBrief as tt, gitHubPullRequestSourceLayer as u, reviewInstructions as un, ListReviewUnits as ut, ReviewRetirementReport as v, ChangedFile as vn, fanOutHandlersLayerFor as vt, ReviewExecutionContext as w, makeFanOutReviewSuite as wt, retireStaleReviews as x, annotatePatch as xn, fileReviewPolicy as xt, decideReviewRetirement as y, ChangedFileStatus as yn, fanOutReviewInstructions as yt, selectReviewRange as z, FileDiffQuery as zt };
+export { FanOutReviewToolkit as $, ReadFile as $t, ReviewStateAuthenticator as A, isReviewableFile as An, ReviewUnit as At, selectedPullRequestSourceLayer as B, FileDiffView as Bt, MAX_REVIEW_STATE_MARKER_CHARS as C, ChangedFile as Cn, makeFanOutReviewInstructions as Ct, ReviewScopeMode as D, annotatePatch as Dn, MAX_MERGED_FINDINGS as Dt, ReviewMode as E, MAX_REVIEW_CONTENT_CHARS as En, mapFileReviewChildFailure as Et, buildProfileMission as F, rankAndDedupeFindings as Ft, webCryptoReviewStateAuthenticatorLayer as G, ListChangedFiles as Gt, toStoredFinding as H, FileSliceQuery as Ht, computeProfileFingerprint as I, ChangedFileSummary as It, extractFingerprint as J, MAX_FINDINGS as Jt, FINGERPRINT_MARKER_LENGTH as K, ListChangedFilesQuery as Kt, fromStoredConcern as L, ChangedFilesView as Lt, ReviewStateMarkerTooLarge as M, renderReviewContent as Mn, ReviewUnitPlan as Mt, StoredReviewConcern as N, UNIT_CHANGED_LINE_BUDGET as Nt, ReviewState as O, commentableLines as On, MAX_REVIEW_UNITS as Ot, StoredReviewFinding as P, planReviewUnits as Pt, FanOutCoordinatorToolkitLayer as Q, REVIEW_TOOL_RESULT_MAX_BYTES as Qt, fromStoredFinding as R, CodeReview as Rt, GitCommitSha as S, normalizeRepoRelativePath as Sn, fileReviewerInstructions as St, ReviewHeadComparison as T, ChangedPath as Tn, makeFileReviewerInstructions as Tt, unavailableReviewStateAuthenticatorLayer as U, FindingCategory as Ut, toStoredConcern as V, FileSlice as Vt, validateReviewState as W, FindingSeverity as Wt, DelegateFileReview as X, MAX_WALKTHROUGH_SUMMARY_CHARS as Xt, renderFingerprintMarker as Y, MAX_WALKTHROUGH_ENTRIES as Yt, FanOutCoordinatorToolkit as Z, PullRequestReviewer as Zt, ReviewRetirementHost as _, MAX_FILE_CHARS as _n, fanOutHandlersLayer as _t, PriorReviews as a, ReviewToolkitLayer as an, FileReviewToolkit as at, hasReviewMetadataMarker as b, PullRequestSourceFailure as bn, fileReviewDelegation as bt, fingerprintUnchanged as c, clampMaxFindings as cn, FileReviewUnitResult as ct, gitHubReviewPublisherLayer as d, makeReviewInstructions as dn, ListReviewUnitsQuery as dt, ReadFileDiff as en, FanOutReviewer as et, gitHubReviewRetirementHostLayer as f, readFileDiffHandler as fn, MAX_CHILD_CONCERNS as ft, ReviewRetirementFailure as g, MAX_CHANGED_FILES as gn, defaultFileReviewerPolicy as gt, RetirableReviewComment as h, reviewInstructions as hn, defaultFanOutPolicy as ht, PriorReviewLookupFailure as i, ReviewToolkit as in, FileReviewRequest as it, ReviewStateMarker as j, parsePatch as jn, ReviewUnitId as jt, ReviewStateAuthenticationFailure as k, hasReviewableContent as kn, MAX_UNIT_FILES as kt, gitHubPriorReviewsLayer as l, defaultReviewPolicy as ln, FileReviewer as lt, RetirableReview as m, resolveGuidance as mn, MAX_FILE_REVIEW_TOOL_CALLS as mt, GitHubApiFailure as n, ReviewFinding as nn, FileReviewDelegationFailure as nt, PublishedReview as o, ReviewVerdict as on, FileReviewToolkitLayer as ot, parseGitHubSubmittedAt as p, readFileHandler as pn, MAX_CHILD_FINDINGS as pt, computeChangesetFingerprint as q, MAX_CONCERNS as qt, GitHubReviewTarget as r, ReviewMission as rn, FileReviewReport as rt, ReviewPublisher as s, WalkthroughEntry as sn, FileReviewUnitFailed as st, DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN as t, ReviewConcern as tn, FileReviewBrief as tt, gitHubPullRequestSourceLayer as u, listChangedFilesHandler as un, ListReviewUnits as ut, ReviewRetirementReport as v, PullRequestMetadata as vn, fanOutHandlersLayerFor as vt, ReviewExecutionContext as w, ChangedFileStatus as wn, makeFanOutReviewSuite as wt, retireStaleReviews as x, ReviewInputViolation as xn, fileReviewPolicy as xt, decideReviewRetirement as y, PullRequestSource as yn, fanOutReviewInstructions as yt, selectReviewRange as z, FileDiffQuery as zt };
 
-//# sourceMappingURL=github-5TCFrxfX.mjs.map
+//# sourceMappingURL=github-mmanX6hk.mjs.map