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

package/src/action.ts

@@ -7,6 +7,8 @@ import { InvalidEffortInput, parseEffortPosition, type EffortPosition } from "./
 import { PrReview, type RunReviewOptions } from "./internal/factory.ts";
 import { readGitHubEvent, resolveReviewTarget, gitHubReviewLayers } from "./internal/github-env.ts";
 import { PriorReviews } from "./internal/github.ts";
+import { compactReviewLoggingLayer } from "./internal/logging.ts";
+import { ReviewProgressReporter } from "./internal/progress.ts";
 import {
   anthropicClientLayer,
   DEFAULT_PROVIDER,
@@ -92,6 +94,7 @@ export interface ResolvedActionInputs {
   readonly failOn: FailOnPolicy;
   readonly skipUnchanged: boolean;
   readonly retireStaleReviews: boolean;
+  readonly progressComment: boolean;
 }
 
 /** Read the PR_REVIEW_* input surface (all optional, all defaulted). */
@@ -135,6 +138,9 @@ export const resolveActionInputs = Effect.fn("resolveActionInputs")(function* ()
   const retireStaleReviews = yield* Config.boolean("PR_REVIEW_RETIRE_STALE_REVIEWS").pipe(
     Config.withDefault(true),
   );
+  const progressComment = yield* Config.boolean("PR_REVIEW_PROGRESS_COMMENT").pipe(
+    Config.withDefault(true),
+  );
   return {
     provider,
     model: Option.getOrUndefined(model),
@@ -154,6 +160,7 @@ export const resolveActionInputs = Effect.fn("resolveActionInputs")(function* ()
     failOn,
     skipUnchanged,
     retireStaleReviews,
+    progressComment,
   } satisfies ResolvedActionInputs;
 });
 
@@ -408,6 +415,13 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
     readonly priorReviews?: PriorReviews["Service"] | undefined;
     /** Retire marker-bearing prior reviews after a successful post (default true). */
     readonly retireStaleReviews?: boolean | undefined;
+    /**
+     * Maintain one sticky "review in progress" issue comment, updated in
+     * place when the run settles. Default false here for custom-harness
+     * compatibility; the packaged action enables it by default. Dry runs
+     * (`post: false`) never post progress.
+     */
+    readonly progressComment?: boolean | undefined;
   } = {},
 ) =>
   Effect.gen(function* () {
@@ -561,7 +575,37 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
         `Reviewing ${target.repository}#${target.number} (${options.post === false ? "dry run" : "posting"})...`,
       );
       const runUrl = yield* resolveRunUrl();
-      const reviewEffect = reviewer.run({ post: options.post ?? true, runUrl });
+      // Progress is a cosmetic, fail-open narration surface: it says a run is
+      // working the moment execution starts and is overwritten in place when
+      // the run settles. It never gates or delays the review itself.
+      const progress =
+        options.progressComment === true && options.post !== false
+          ? Option.some(yield* ReviewProgressReporter)
+          : Option.none<ReviewProgressReporter["Service"]>();
+      if (Option.isSome(progress)) {
+        const source = yield* PullRequestSource;
+        const headMetadata = yield* source.metadata.pipe(Effect.orElseSucceed(() => undefined));
+        yield* progress.value.begin({
+          headSha: headMetadata?.headSha,
+          reviewMode: selection?.mode,
+          reviewReason: selection?.reason,
+          filesInScope: selection?.files.length,
+          modelLabel: options.modelLabel,
+          runUrl,
+        });
+      }
+      const runReview = reviewer.run({ post: options.post ?? true, runUrl });
+      const reviewEffect = Option.isSome(progress)
+        ? runReview.pipe(
+            Effect.tapCause(() =>
+              progress.value.settle({
+                outcome: "failed",
+                runUrl,
+                modelLabel: options.modelLabel,
+              }),
+            ),
+          )
+        : runReview;
       const outcome = yield* selection === undefined
         ? reviewEffect
         : reviewEffect.pipe(
@@ -597,6 +641,17 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
         }
       }
       const check = concludeReviewOutcome(outcome);
+      if (Option.isSome(progress)) {
+        yield* progress.value.settle({
+          outcome: "reviewed",
+          conclusion: check.conclusion,
+          verdict: outcome.review.verdict,
+          inlineComments: outcome.plan.comments.length,
+          reviewUrl: outcome.published?.url,
+          runUrl,
+          modelLabel: options.modelLabel,
+        });
+      }
       yield* writeActionOutputs(outcomeOutputs(outcome, check.conclusion));
       yield* writeStepSummary(outcomeSummary(outcome, options.modelLabel, check.conclusion));
       if (check.conclusion !== "success") {
@@ -651,6 +706,7 @@ export const reviewActionProgram = Effect.gen(function* () {
     skipUnchanged: inputs.skipUnchanged,
     reviewMode: inputs.reviewMode,
     retireStaleReviews: inputs.retireStaleReviews,
+    progressComment: inputs.progressComment,
     modelLabel,
   };
   if (inputs.provider === "anthropic") {
@@ -683,7 +739,9 @@ export const main = (): void =>
         ),
       ),
       Effect.scoped,
-      Effect.provide(Layer.merge(NodeServices.layer, FetchHttpClient.layer)),
+      Effect.provide(
+        Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer, compactReviewLoggingLayer),
+      ),
     ),
     { disableErrorReporting: true },
   );

package/src/index.ts

@@ -10,7 +10,9 @@ export * from "./internal/fingerprint.ts";
 export * from "./internal/github.ts";
 export * from "./internal/github-env.ts";
 export * from "./internal/ignore.ts";
+export * from "./internal/logging.ts";
 export * from "./internal/profiles.ts";
+export * from "./internal/progress.ts";
 export * from "./internal/providers.ts";
 export * from "./internal/render.ts";
 export * from "./internal/retirement.ts";

package/src/internal/action-entry.ts

@@ -26,6 +26,8 @@ const INPUT_TO_ENV: ReadonlyArray<readonly [input: string, env: string]> = [
   ["INPUT_FAIL-ON", "PR_REVIEW_FAIL_ON"],
   ["INPUT_SKIP-UNCHANGED", "PR_REVIEW_SKIP_UNCHANGED"],
   ["INPUT_RETIRE-STALE-REVIEWS", "PR_REVIEW_RETIRE_STALE_REVIEWS"],
+  ["INPUT_PROGRESS-COMMENT", "PR_REVIEW_PROGRESS_COMMENT"],
+  ["INPUT_LOG-LEVEL", "PR_REVIEW_LOG_LEVEL"],
   ["INPUT_STATE-SECRET", "PR_REVIEW_STATE_SECRET"],
   ["INPUT_REVIEW-AUTHOR", "PR_REVIEW_AUTHOR_LOGIN"],
   ["INPUT_OPENAI-API-KEY", "OPENAI_API_KEY"],

package/src/internal/coverage.ts

@@ -2,8 +2,9 @@ import { Option, Schema } from "effect";
 import type { RunEvent } from "effect-agent";
 
 import type { ChangedFile } from "./diff.ts";
+import { isReviewableFile } from "./diff.ts";
 import { FileReviewDelegationFailure, FileReviewRequest, FileReviewUnitResult } from "./fan-out.ts";
-import { FileDiffQuery } from "./review-agent.ts";
+import { FileDiffQuery, type WalkthroughEntry } from "./review-agent.ts";
 import { planReviewUnits } from "./review-units.ts";
 
 // ---------------------------------------------------------------------------
@@ -95,7 +96,7 @@ const flatCoverage = (
     if (trace.succeeded.has(toolCallId)) reviewed.add(query.value.path);
     if (trace.failed.has(toolCallId)) failedPaths.add(query.value.path);
   }
-  const undiffable = files.filter((file) => file.patch === undefined).map((file) => file.path);
+  const undiffable = files.filter((file) => !isReviewableFile(file)).map((file) => file.path);
   const unreviewed = requiredPaths.filter(
     (path) => !reviewed.has(path) || undiffable.includes(path) || failedPaths.has(path),
   );
@@ -104,7 +105,9 @@ const flatCoverage = (
     reasons.push(`review range exposed ${files.length} of ${totalFiles} required files`);
   }
   if (undiffable.length > 0) {
-    reasons.push(boundedListReason("required paths have no textual diff", undiffable));
+    reasons.push(
+      boundedListReason("required paths have no reviewable diff or bounded text", undiffable),
+    );
   }
   if (failedPaths.size > 0) {
     reasons.push(boundedListReason("diff reads failed", failedPaths));
@@ -196,7 +199,12 @@ const fanOutCoverage = (
     reasons.push(`review range exposed ${files.length} of ${totalFiles} required files`);
   }
   if (plan.undiffablePaths.length > 0) {
-    reasons.push(boundedListReason("required paths have no textual diff", plan.undiffablePaths));
+    reasons.push(
+      boundedListReason(
+        "required paths have no reviewable diff or bounded text",
+        plan.undiffablePaths,
+      ),
+    );
   }
   if (plan.unassignedPaths.length > 0) {
     reasons.push(boundedListReason("fan-out capacity left paths unassigned", plan.unassignedPaths));
@@ -219,6 +227,36 @@ const fanOutCoverage = (
   });
 };
 
+/**
+ * Host-verified per-file summaries from the fan-out run's Tool events: for
+ * every successfully settled delegation, the child-reported `fileSummaries`
+ * whose paths belong to that invocation's requested unit. This is the
+ * declassification check `projectResult` cannot perform itself (it never sees
+ * the request): a child assigned file A cannot smuggle a summary for changed
+ * file B into the merged walkthrough, and a coordinator cannot invent or edit
+ * entries — only exact child-reported, in-unit summaries survive.
+ */
+export const collectUnitFileSummaries = (
+  events: ReadonlyArray<RunEvent>,
+): ReadonlyArray<WalkthroughEntry> => {
+  const trace = toolTrace(events);
+  const entries: Array<WalkthroughEntry> = [];
+  for (const [toolCallId, declaration] of trace.declared) {
+    if (declaration.toolName !== "delegate_file_review") continue;
+    const request = Schema.decodeUnknownOption(FileReviewRequest)(declaration.parameters);
+    if (Option.isNone(request)) continue;
+    const success = trace.succeeded.get(toolCallId);
+    if (success === undefined || trace.failed.has(toolCallId)) continue;
+    const result = Schema.decodeUnknownOption(FileReviewUnitResult)(success.result);
+    if (Option.isNone(result) || result.value.unitId !== request.value.unitId) continue;
+    const assigned = new Set(request.value.paths);
+    for (const entry of result.value.fileSummaries ?? []) {
+      if (assigned.has(entry.path)) entries.push(entry);
+    }
+  }
+  return entries;
+};
+
 /** Assess one settled run without trusting its prose summary or verdict. */
 export const assessReviewCoverage = (input: {
   readonly shape: ReviewShape;

package/src/internal/diff.ts

@@ -31,8 +31,67 @@ export class ChangedFile extends Schema.Class<ChangedFile>("@effect-agent/pr-rev
   previousPath: Schema.optionalKey(ChangedPath),
   /** Unified-diff hunks; absent for binary or oversized files. */
   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(200_000))),
+  reviewHeadContent: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(200_000))),
 }) {}
 
+/** Complete rendered fallback evidence must fit one ordinary model context. */
+export const MAX_REVIEW_CONTENT_CHARS = 220_000;
+
+/**
+ * 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.
+ */
+export const renderReviewContent = (file: ChangedFile): string | undefined => {
+  if (file.patch !== undefined) return undefined;
+  const includeBase = file.status !== "added";
+  const includeHead = file.status !== "removed";
+  const sections: Array<string> = [
+    "[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: string): boolean => {
+    const nextLength = renderedLength + 1 + part.length;
+    if (nextLength > MAX_REVIEW_CONTENT_CHARS) return false;
+    sections.push(part);
+    renderedLength = nextLength;
+    return true;
+  };
+  const appendSide = (side: "B" | "H", header: string, content: string): boolean => {
+    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 === undefined) return undefined;
+    if (!appendSide("B", "[BASE VERSION]", file.reviewBaseContent)) return undefined;
+  }
+  if (includeHead) {
+    if (file.reviewHeadContent === undefined) return undefined;
+    if (!appendSide("H", "[HEAD VERSION]", file.reviewHeadContent)) return undefined;
+  }
+  return sections.join("\n");
+};
+
+/** Whether complete patchless evidence fits the model-facing review bound. */
+export const hasReviewableContent = (file: ChangedFile): boolean =>
+  renderReviewContent(file) !== undefined;
+
+/** Whether the reviewer has either a real patch or bounded textual fallback evidence. */
+export const isReviewableFile = (file: ChangedFile): boolean =>
+  file.patch !== undefined || hasReviewableContent(file);
+
 /** One parsed line of a unified diff, with both coordinate systems. */
 export interface PatchLine {
   readonly kind: "context" | "add" | "del";

package/src/internal/fan-out.ts

@@ -6,6 +6,7 @@ import {
   SubagentPolicy,
   SubagentRuntime,
   ToolExecutionClass,
+  ToolResultBounds,
   type RuntimeBinding,
 } from "effect-agent";
 import { Tool, Toolkit } from "effect/unstable/ai";
@@ -15,13 +16,16 @@ import {
   clampMaxFindings,
   CodeReview,
   MAX_CONCERNS,
+  MAX_WALKTHROUGH_SUMMARY_CHARS,
   ReadFile,
   ReadFileDiff,
   readFileDiffHandler,
   readFileHandler,
+  REVIEW_TOOL_RESULT_MAX_BYTES,
   ReviewConcern,
   ReviewFinding,
   ReviewMission,
+  WalkthroughEntry,
 } from "./review-agent.ts";
 import {
   MAX_REVIEW_UNITS,
@@ -92,6 +96,10 @@ export class FileReviewReport extends Schema.Class<FileReviewReport>(
   concerns: Schema.optionalKey(
     Schema.Array(ReviewConcern).check(Schema.isMaxLength(MAX_CHILD_CONCERNS)),
   ),
+  /** One-sentence per-file change summaries for the merged walkthrough. */
+  fileSummaries: Schema.optionalKey(
+    Schema.Array(WalkthroughEntry).check(Schema.isMaxLength(MAX_UNIT_FILES)),
+  ),
 }) {}
 
 /**
@@ -120,12 +128,13 @@ export const makeFileReviewerInstructions =
       `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 (<= ${MAX_WALKTHROUGH_SUMMARY_CHARS} 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 ${MAX_CHILD_FINDINGS} findings and at most ${MAX_CHILD_CONCERNS} 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");
 
@@ -137,10 +146,15 @@ export const defaultFileReviewerPolicy = AgentPolicy.make({
   maxToolCalls: MAX_FILE_REVIEW_TOOL_CALLS,
   maxDuration: "6 minutes",
   toolConcurrency: 2,
+  // Same rationale as the flat reviewer's bound: read refusals are
+  // model-visible results, and one parallel batch of out-of-unit probes must
+  // not kill the child before it has seen a single refusal.
+  repeatedFailureLimit: 12,
   tokenBudget: 200_000,
   // Bound one live prompt independently from cumulative usage. The engine
   // prunes old diff/file results before paying for a summary.
   contextTokenLimit: 150_000,
+  toolResultBounds: ToolResultBounds.make({ maxBytes: REVIEW_TOOL_RESULT_MAX_BYTES }),
   // Typed exhaustion, deliberately NOT the final-answer soft landing: a
   // review is a coverage claim, and a child whose reads were rejected could
   // still emit schema-valid findings — laundering budget exhaustion into
@@ -176,6 +190,10 @@ export class FileReviewUnitResult extends Schema.Class<FileReviewUnitResult>(
   concerns: Schema.optionalKey(
     Schema.Array(ReviewConcern).check(Schema.isMaxLength(MAX_CHILD_CONCERNS)),
   ),
+  /** One-sentence per-file change summaries for the merged walkthrough. */
+  fileSummaries: Schema.optionalKey(
+    Schema.Array(WalkthroughEntry).check(Schema.isMaxLength(MAX_UNIT_FILES)),
+  ),
 }) {}
 
 /**
@@ -284,7 +302,8 @@ export const makeFanOutReviewInstructions =
       '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 ${MAX_CONCERNS}.`,
-      '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");
   };
@@ -364,6 +383,7 @@ const makeFileReviewDelegation = (child: ReturnType<typeof makeFileReviewerDefin
           unitId: report.unitId,
           findings: report.findings,
           ...(report.concerns !== undefined ? { concerns: report.concerns } : {}),
+          ...(report.fileSummaries !== undefined ? { fileSummaries: report.fileSummaries } : {}),
         }),
       ),
     policy: fileReviewPolicy,

package/src/internal/fingerprint.ts

@@ -57,7 +57,7 @@ const canonicalChangeset = (files: ReadonlyArray<ChangedFile>): string =>
   files
     .map(
       (file) =>
-        `${file.path}${FIELD}${file.status}${FIELD}${String(file.additions)}${FIELD}${String(file.deletions)}${FIELD}${file.patch ?? ""}`,
+        `${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);

package/src/internal/fixtures.ts

@@ -28,6 +28,7 @@ import {
 /** One fixture file: its changeset entry plus optional head content. */
 export class FixtureFile extends Schema.Class<FixtureFile>("@effect-agent/pr-review/FixtureFile")({
   file: ChangedFile,
+  baseContent: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAX_FILE_CHARS))),
   headContent: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAX_FILE_CHARS))),
 }) {}
 
@@ -57,12 +58,21 @@ const requireChanged = (
 /** Deterministic `PullRequestSource` over one fixture pull request. */
 export const fixturePullRequestSourceLayer = (
   fixture: FixturePullRequest,
-): Layer.Layer<PullRequestSource> =>
-  Layer.succeed(PullRequestSource)(
+): Layer.Layer<PullRequestSource> => {
+  const files = fixture.files.map((entry) =>
+    entry.file.patch !== undefined
+      ? entry.file
+      : ChangedFile.make({
+          ...entry.file,
+          ...(entry.baseContent === undefined ? {} : { reviewBaseContent: entry.baseContent }),
+          ...(entry.headContent === undefined ? {} : { reviewHeadContent: entry.headContent }),
+        }),
+  );
+  return Layer.succeed(PullRequestSource)(
     PullRequestSource.of({
       metadata: Effect.succeed(fixture.metadata),
-      changedFiles: Effect.succeed(fixture.files.map((entry) => entry.file)),
-      anchorFiles: Effect.succeed(fixture.files.map((entry) => entry.file)),
+      changedFiles: Effect.succeed(files),
+      anchorFiles: Effect.succeed(files),
       readFile: (path) =>
         Effect.gen(function* () {
           const relative = yield* normalizeRepoRelativePath(path);
@@ -77,6 +87,7 @@ export const fixturePullRequestSourceLayer = (
         }),
     }),
   );
+};
 
 /** In-memory publisher: records every plan and mints a deterministic receipt. */
 export const collectingReviewPublisherLayer = (

package/src/internal/github-env.ts

@@ -10,6 +10,8 @@ import {
   gitHubReviewPublisherLayer,
   gitHubReviewRetirementHostLayer,
 } from "./github.ts";
+import type { ReviewProgressReporter } from "./progress.ts";
+import { gitHubReviewProgressLayer } from "./progress.ts";
 import type { ReviewRetirementHost } from "./retirement.ts";
 import type { PullRequestSource } from "./source.ts";
 
@@ -110,7 +112,11 @@ export const resolveReviewTarget = Effect.fn("resolveReviewTarget")(function* (o
 export const gitHubReviewLayers = (
   target: ResolvedReviewTarget,
 ): Layer.Layer<
-  PullRequestSource | ReviewPublisher | PriorReviews | ReviewRetirementHost,
+  | PullRequestSource
+  | ReviewPublisher
+  | PriorReviews
+  | ReviewRetirementHost
+  | ReviewProgressReporter,
   Config.ConfigError,
   HttpClient.HttpClient
 > =>
@@ -143,6 +149,7 @@ export const gitHubReviewLayers = (
         gitHubReviewPublisherLayer.pipe(Layer.provide(targetLayer)),
         gitHubPriorReviewsLayer.pipe(Layer.provide(targetLayer)),
         gitHubReviewRetirementHostLayer.pipe(Layer.provide(targetLayer)),
+        gitHubReviewProgressLayer.pipe(Layer.provide(targetLayer)),
       );
     }),
   );

package/src/internal/github.ts

@@ -313,21 +313,13 @@ export const gitHubPullRequestSourceLayer: Layer.Layer<
     const metadata = yield* Effect.cached(
       fetchMetadata.pipe(Effect.provideService(HttpClient.HttpClient, client)),
     );
-    const changedFiles = yield* Effect.cached(
+    const rawFiles = yield* Effect.cached(
       fetchFiles.pipe(Effect.provideService(HttpClient.HttpClient, client)),
     );
 
-    const readFile = (path: string) =>
+    const readRepositoryFile = (path: string, ref: string) =>
       Effect.gen(function* () {
         const relative = yield* normalizeRepoRelativePath(path);
-        const files = yield* changedFiles;
-        if (!files.some((file) => file.path === relative)) {
-          return yield* ReviewInputViolation.make({
-            input: relative,
-            reason: "Path is not part of this pull request's changeset.",
-          });
-        }
-        const head = yield* metadata;
         const encodedPath = relative.split("/").map(encodeURIComponent).join("/");
         const response = yield* executeOk(
           "readFile",
@@ -336,12 +328,32 @@ export const gitHubPullRequestSourceLayer: Layer.Layer<
               `${target.apiUrl}/repos/${target.repository}/contents/${encodedPath}`,
             ).pipe(
               HttpClientRequest.accept("application/vnd.github.raw+json"),
-              HttpClientRequest.setUrlParams({ ref: head.headSha }),
+              HttpClientRequest.setUrlParams({ ref }),
             ),
             target.token,
           ),
         ).pipe(Effect.provideService(HttpClient.HttpClient, client));
-        const text = yield* response.text.pipe(Effect.mapError(failWith("readFile")));
+        const buffer = yield* response.arrayBuffer.pipe(Effect.mapError(failWith("readFile")));
+        if (buffer.byteLength > MAX_FILE_CHARS) {
+          return yield* ReviewInputViolation.make({
+            input: relative,
+            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("\u0000")) {
+          return yield* ReviewInputViolation.make({
+            input: relative,
+            reason: "File contains binary NUL bytes.",
+          });
+        }
         if (text.length > MAX_FILE_CHARS) {
           return yield* ReviewInputViolation.make({
             input: relative,
@@ -351,6 +363,55 @@ export const gitHubPullRequestSourceLayer: Layer.Layer<
         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 !== undefined) return Effect.succeed(file);
+            const basePath = file.previousPath ?? file.path;
+            const base =
+              file.status === "added"
+                ? Effect.succeed(Option.none<string>())
+                : readRepositoryFile(basePath, pullRequest.baseSha ?? pullRequest.baseRef).pipe(
+                    Effect.option,
+                  );
+            const head =
+              file.status === "removed"
+                ? Effect.succeed(Option.none<string>())
+                : 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: string) =>
+      Effect.gen(function* () {
+        const relative = yield* normalizeRepoRelativePath(path);
+        const files = yield* changedFiles;
+        const file = files.find((candidate) => candidate.path === relative);
+        if (file === undefined) {
+          return yield* ReviewInputViolation.make({
+            input: relative,
+            reason: "Path is not part of this pull request's changeset.",
+          });
+        }
+        if (file.reviewHeadContent !== undefined) return file.reviewHeadContent;
+        const head = yield* metadata;
+        return yield* readRepositoryFile(relative, head.headSha);
+      });
+
     return PullRequestSource.of({ metadata, changedFiles, anchorFiles: changedFiles, readFile });
   }),
 );