@effect-agent/pr-review 0.1.0-beta.22 → 0.1.0-beta.24

package/src/internal/fingerprint.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Crypto, Effect, Encoding } from "effect";
 
 import type { ChangedFile } from "./diff.ts";
 
@@ -36,14 +36,14 @@ export const extractFingerprint = (body: string): string | undefined => {
   return last;
 };
 
-/** WebCrypto SHA-256; unavailable crypto is a defect, not an expected failure. */
-const sha256Hex = (text: string): Effect.Effect<string> =>
-  Effect.promise(async () => {
-    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-    return Array.from(new Uint8Array(digest))
-      .map((byte) => byte.toString(16).padStart(2, "0"))
-      .join("");
-  });
+/** SHA-256 via `Crypto.Crypto`; unavailable crypto is a defect, not an expected failure. */
+const sha256Hex = Effect.fn("sha256Hex")(function* (
+  text: string,
+): Effect.fn.Return<string, never, Crypto.Crypto> {
+  const crypto = yield* Crypto.Crypto;
+  const digest = yield* crypto.digest("SHA-256", new TextEncoder().encode(text)).pipe(Effect.orDie);
+  return Encoding.encodeHex(digest);
+});
 
 const FIELD = "\u0000";
 const RECORD = "\u0001";
@@ -80,4 +80,10 @@ const canonicalChangeset = (files: ReadonlyArray<ChangedFile>): string =>
 export const computeChangesetFingerprint = (
   files: ReadonlyArray<ChangedFile>,
   signature: string,
-): Effect.Effect<string> => sha256Hex(`${canonicalChangeset(files)}${SECTION}${signature}`);
+): Effect.Effect<string, never, Crypto.Crypto> =>
+  sha256Hex(`${canonicalChangeset(files)}${SECTION}${signature}`);
+
+/** Profile fingerprints are SHA-256 over configuration-only signatures. */
+export const computeProfileFingerprint = (
+  signature: string,
+): Effect.Effect<string, never, Crypto.Crypto> => sha256Hex(signature);

package/src/internal/fixtures.ts

@@ -120,6 +120,7 @@ export const staticPriorReviews = (
   options: {
     readonly state?: Option.Option<ReviewState> | undefined;
     readonly comparison?: ReviewHeadComparison | undefined;
+    readonly treeComparison?: ReviewHeadComparison | undefined;
   } = {},
 ): PriorReviews["Service"] =>
   PriorReviews.of({
@@ -129,6 +130,10 @@ export const staticPriorReviews = (
       options.comparison === undefined
         ? Effect.fail(PriorReviewLookupFailure.make({ reason: "no fixture comparison" }))
         : Effect.succeed(options.comparison),
+    compareTrees: () =>
+      options.treeComparison === undefined
+        ? Effect.fail(PriorReviewLookupFailure.make({ reason: "no fixture tree comparison" }))
+        : Effect.succeed(options.treeComparison),
   });
 
 /** Layer form for consumers whose Effect explicitly requires `PriorReviews`. */
@@ -137,6 +142,7 @@ export const staticPriorReviewsLayer = (
   options: {
     readonly state?: Option.Option<ReviewState> | undefined;
     readonly comparison?: ReviewHeadComparison | undefined;
+    readonly treeComparison?: ReviewHeadComparison | undefined;
   } = {},
 ): Layer.Layer<PriorReviews> =>
   Layer.succeed(PriorReviews)(staticPriorReviews(fingerprint, options));

package/src/internal/github.ts

@@ -130,8 +130,9 @@ const GitHubReviewCommentWire = Schema.Struct({
   node_id: Schema.String,
   path: Schema.String,
   body: Schema.String,
-  line: Schema.NullOr(Schema.Int),
-  original_line: Schema.NullOr(Schema.Int),
+  // Outdated comments omit `line` entirely instead of sending null.
+  line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  original_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
   start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
   original_start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
 });
@@ -578,8 +579,11 @@ export const gitHubReviewRetirementHostLayer: Layer.Layer<
         }).pipe(
           Effect.map((comments) =>
             comments.map((comment) => {
-              const endLine = comment.line ?? comment.original_line;
-              const startLine = comment.start_line ?? comment.original_start_line ?? endLine;
+              const positiveLine = (value: number | null | undefined): number | null =>
+                value !== undefined && value !== null && value > 0 ? value : null;
+              const endLine = positiveLine(comment.line ?? comment.original_line);
+              const startLine =
+                positiveLine(comment.start_line ?? comment.original_start_line) ?? endLine;
               return RetirableReviewComment.make({
                 nodeId: comment.node_id,
                 path: comment.path,
@@ -672,6 +676,15 @@ export class PriorReviews extends Context.Service<
       baseSha: string,
       headSha: string,
     ) => Effect.Effect<ReviewHeadComparison, PriorReviewLookupFailure>;
+    /**
+     * Two-dot tree comparison (`base..head`). Used when the reviewed head is
+     * not a git ancestor so a rebase or amend can still name the paths whose
+     * blob contents actually changed.
+     */
+    readonly compareTrees: (
+      baseSha: string,
+      headSha: string,
+    ) => Effect.Effect<ReviewHeadComparison, PriorReviewLookupFailure>;
   }
 >()("@effect-agent/pr-review/PriorReviews") {}
 
@@ -775,12 +788,12 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
         }
         return { latestFingerprint: latest, latestState };
       }).pipe(Effect.provideService(HttpClient.HttpClient, client));
-    const compareHeads = (baseSha: string, headSha: string) =>
+    const compareCommits = (baseSha: string, headSha: string, separator: "..." | "..") =>
       Effect.gen(function* () {
         const response = yield* HttpClient.execute(
           withCommonHeaders(
             HttpClientRequest.get(
-              `${target.apiUrl}/repos/${target.repository}/compare/${encodeURIComponent(baseSha)}...${encodeURIComponent(headSha)}`,
+              `${target.apiUrl}/repos/${target.repository}/compare/${encodeURIComponent(baseSha)}${separator}${encodeURIComponent(headSha)}`,
             ).pipe(HttpClientRequest.acceptJson),
             target.token,
           ),
@@ -803,6 +816,21 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
           truncated: files.length >= MAX_CHANGED_FILES,
         });
       }).pipe(Effect.provideService(HttpClient.HttpClient, client));
+    const compareTrees = (baseSha: string, headSha: string) =>
+      compareCommits(baseSha, headSha, "..").pipe(
+        Effect.map((comparison) =>
+          ReviewHeadComparison.make({
+            // This is a content snapshot, not a lineage claim. Selection
+            // intersects these files with the current PR path set.
+            status: comparison.status === "identical" ? "identical" : "ahead",
+            baseSha,
+            headSha,
+            mergeBaseSha: baseSha,
+            files: comparison.files,
+            truncated: comparison.truncated,
+          }),
+        ),
+      );
     return PriorReviews.of({
       latestFingerprint: readMarkers(Option.none()).pipe(
         Effect.map((markers) => markers.latestFingerprint),
@@ -813,7 +841,8 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
           Effect.map((markers) => markers.latestState),
         );
       }),
-      compareHeads,
+      compareHeads: (baseSha, headSha) => compareCommits(baseSha, headSha, "..."),
+      compareTrees,
     });
   }),
 );

package/src/internal/profiles.ts

@@ -38,18 +38,18 @@ export const pullRequestReviewerProfile = PullRequestReviewerProfile.make({
 export class FanOutReviewerProfile extends Schema.Class<FanOutReviewerProfile>(
   "@effect-agent/pr-review/FanOutReviewerProfile",
 )({
-  /** Ephemeral runtime: one bounded AgentRuntime.run per invocation. */
+  /** Ephemeral runtime: bounded host-scheduled child runs per invocation. */
   deploymentClass: Schema.Literal("E"),
-  /** Every model-callable tool — parent and child — is a read; none mutate. */
+  /** Every model-callable surface is evidence-only; children expose no tools. */
   readOnlyToolSurface: Schema.Literal(true),
   /** The review is posted by the host AFTER the run settles, never by a tool. */
   publicationOutsideAgentLoop: Schema.Literal(true),
   /** Child findings are untrusted; anchors are validated against the parsed diff. */
   anchorsValidatedBeforePublication: Schema.Literal(true),
-  /** S1 attached ephemeral delegation at depth 1; nested delegation is rejected. */
-  attachedEphemeralDelegation: Schema.Literal(true),
-  /** A failed unit surfaces to the coordinator as a typed failed result, never retried. */
-  failedUnitsReportedNotRetried: Schema.Literal(true),
+  /** Host code schedules every pass from the deterministic plan; no coordinator model. */
+  hostScheduledPasses: Schema.Literal(true),
+  /** A failed pass is retried once, then reported and carried as unreviewed scope. */
+  failedPassesRetriedOnceThenCarried: Schema.Literal(true),
   /** Risk categories and required specialist passes are pure host policy. */
   hostOwnedRiskClassification: Schema.Literal(true),
   /** Every host-classified high-risk unit receives a fresh specialist pass. */
@@ -69,8 +69,8 @@ export const fanOutReviewerProfile = FanOutReviewerProfile.make({
   readOnlyToolSurface: true,
   publicationOutsideAgentLoop: true,
   anchorsValidatedBeforePublication: true,
-  attachedEphemeralDelegation: true,
-  failedUnitsReportedNotRetried: true,
+  hostScheduledPasses: true,
+  failedPassesRetriedOnceThenCarried: true,
   hostOwnedRiskClassification: true,
   redundantHighRiskDiscovery: true,
   independentCandidateVerification: true,

package/src/internal/render.ts

@@ -2,7 +2,7 @@ import { Schema } from "effect";
 
 import { anchorViolation } from "./anchors.ts";
 export { anchorViolation } from "./anchors.ts";
-import type { ReviewAssurance, ReviewCoverage, ReviewInputCoverage } from "./coverage.ts";
+import type { ReviewAssurance, ReviewInputCoverage } from "./coverage.ts";
 import type { ChangedFile } from "./diff.ts";
 import { renderFingerprintMarker } from "./fingerprint.ts";
 import {
@@ -215,27 +215,27 @@ const renderVerdictCallout = (
   options: {
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
-    readonly coverage?: ReviewCoverage | undefined;
     readonly inputCoverage?: ReviewInputCoverage | undefined;
     readonly assurance?: ReviewAssurance | undefined;
+    readonly unreviewedPaths?: ReadonlyArray<string> | undefined;
   },
 ): string => {
   const counts = severityCounts(review, options.carriedFindings, options.carriedConcerns);
+  // Code findings outrank machinery gaps: a blocking finding is the
+  // actionable signal, and unsettled reviewer-side work is carried forward.
+  if (counts.blocking > 0) {
+    return `> [!CAUTION]\n> ${countNoun(counts.blocking, "blocking finding")} — do not merge before addressing ${counts.blocking === 1 ? "it" : "them"}.`;
+  }
+  const carried = options.unreviewedPaths?.length ?? 0;
   if (
     options.inputCoverage?.status === "incomplete" ||
-    (options.inputCoverage === undefined && options.coverage?.status === "incomplete")
+    options.assurance?.status === "incomplete"
   ) {
-    const suffix =
-      counts.blocking > 0 ? ` It also has ${countNoun(counts.blocking, "blocking finding")}.` : "";
-    return `> [!CAUTION]\n> Input coverage is incomplete — the check must not pass.${suffix}`;
-  }
-  if (options.assurance !== undefined && options.assurance.status !== "settled") {
-    const suffix =
-      counts.blocking > 0 ? ` It also has ${countNoun(counts.blocking, "blocking finding")}.` : "";
-    return `> [!CAUTION]\n> Configured review assurance did not settle — the check must not pass.${suffix}`;
-  }
-  if (counts.blocking > 0) {
-    return `> [!CAUTION]\n> ${countNoun(counts.blocking, "blocking finding")} — do not merge before addressing ${counts.blocking === 1 ? "it" : "them"}.`;
+    const carriedNote =
+      carried > 0
+        ? ` ${countNoun(carried, "affected path")} ${carried === 1 ? "is" : "are"} carried forward and retried automatically on the next run.`
+        : "";
+    return `> [!WARNING]\n> Review infrastructure did not settle — a reviewer-side gap, NOT a request to change code.${carriedNote} The check reports "incomplete" until a run settles.`;
   }
   if (counts.important > 0) {
     return `> [!IMPORTANT]\n> ${countNoun(counts.important, "important finding")} to address before merging.`;
@@ -393,22 +393,20 @@ export const planPublication = (
     readonly modelLabel?: string | undefined;
     /** Workflow-run URL rendered into the footer. */
     readonly runUrl?: string | undefined;
-    /** Observed run usage rendered into the footer. */
+    /** Observed whole-run usage rendered into the footer. */
     readonly usage?: { readonly inputTokens: number; readonly outputTokens: number } | undefined;
-    /** What the usage observed: the whole run, or the coordinator only. */
-    readonly usageScope?: "run" | "coordinator" | undefined;
     /**
      * Changeset fingerprint embedded invisibly in the review body so a later
      * run can skip re-reviewing an unchanged changeset.
      */
     readonly fingerprint?: string | undefined;
-    /** Host-owned coverage; incomplete coverage is rendered and fails the check. */
-    readonly coverage?: ReviewCoverage | undefined;
     /** Host-owned path/evidence assignment, separate from review assurance. */
     readonly inputCoverage?: ReviewInputCoverage | undefined;
     /** Host-owned discovery/specialist/verification settlement. */
     readonly assurance?: ReviewAssurance | undefined;
-    /** Unchanged unresolved items carried from the prior settled assurance baseline. */
+    /** Retryable scope this run could not settle; carried to the next run. */
+    readonly unreviewedPaths?: ReadonlyArray<string> | undefined;
+    /** Unchanged unresolved items carried from the prior reviewed baseline. */
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
     /** Selected review scope, made visible whenever orchestration chose it. */
@@ -452,14 +450,8 @@ export const planPublication = (
 
   const footerParts = ["Automated review by @effect-agent/pr-review"];
   if (options.modelLabel !== undefined) footerParts.push(options.modelLabel);
-  // Usage renders only under an EXPLICIT scope: this planner cannot know
-  // whether a budget snapshot observed the whole run or only a fan-out
-  // coordinator, and omitting the number is honest where mislabeling is not.
-  if (options.usage !== undefined && options.usageScope !== undefined) {
-    const scope = options.usageScope === "coordinator" ? " (coordinator)" : "";
-    footerParts.push(
-      `${options.usage.inputTokens} in / ${options.usage.outputTokens} out tokens${scope}`,
-    );
+  if (options.usage !== undefined) {
+    footerParts.push(`${options.usage.inputTokens} in / ${options.usage.outputTokens} out tokens`);
   }
   if (options.runUrl !== undefined) footerParts.push(`[run](${options.runUrl})`);
   footerParts.push(`reviewed at ${options.headSha.slice(0, 7)}`);
@@ -490,9 +482,9 @@ export const planPublication = (
       renderVerdictCallout(review, {
         carriedFindings,
         carriedConcerns,
-        coverage: options.coverage,
         inputCoverage: options.inputCoverage,
         assurance: options.assurance,
+        unreviewedPaths: options.unreviewedPaths,
       }),
     ];
     if (options.reviewMode !== undefined && options.reviewReason !== undefined) {
@@ -513,7 +505,7 @@ export const planPublication = (
     if (options.inputCoverage !== undefined && options.assurance !== undefined) {
       parts.push(
         "",
-        `**Input coverage:** ${options.inputCoverage.status} (${options.inputCoverage.assignedPaths.length}/${options.inputCoverage.requiredPaths.length} paths assigned, ${options.inputCoverage.partialPaths.length} partial) · **Review assurance:** ${options.assurance.status} (${options.assurance.completedGeneralDiscoveryPasses}/${options.assurance.requiredGeneralDiscoveryPasses} general discovery, ${options.assurance.completedSpecialistPasses}/${options.assurance.requiredSpecialistPasses} specialist, ${options.assurance.completedVerificationPasses}/${options.assurance.requiredVerificationPasses} verification; ${options.assurance.confirmedCandidates} confirmed / ${options.assurance.rejectedCandidates} rejected / ${options.assurance.unsettledCandidates} unsettled candidates)`,
+        `**Input coverage:** ${options.inputCoverage.status} (${options.inputCoverage.assignedPaths.length}/${options.inputCoverage.requiredPaths.length} paths assigned, ${options.inputCoverage.partialPaths.length} partial) · **Review assurance:** ${options.assurance.status} (${options.assurance.completedGeneralDiscoveryPasses}/${options.assurance.requiredGeneralDiscoveryPasses} general discovery, ${options.assurance.completedSpecialistPasses}/${options.assurance.requiredSpecialistPasses} specialist, ${options.assurance.completedVerificationPasses}/${options.assurance.requiredVerificationPasses} verification; ${options.assurance.confirmedCandidates} confirmed / ${options.assurance.rejectedCandidates} rejected / ${options.assurance.unsettledCandidates} unsettled${options.assurance.discardedInvalidFindings > 0 ? ` / ${options.assurance.discardedInvalidFindings} discarded` : ""} candidates)`,
       );
     }
     parts.push("", review.summary);
@@ -525,22 +517,17 @@ export const planPublication = (
     if (options.inputCoverage?.status === "incomplete") {
       parts.push(
         "",
-        "### 🛑 Incomplete input coverage",
+        "### ⚠️ Incomplete input coverage",
         "",
         ...options.inputCoverage.reasons.map((reason) => `- ${reason}`),
       );
-    } else if (options.inputCoverage === undefined && options.coverage?.status === "incomplete") {
-      parts.push(
-        "",
-        "### 🛑 Incomplete coverage",
-        "",
-        ...options.coverage.reasons.map((reason) => `- ${reason}`),
-      );
     }
-    if (options.assurance !== undefined && options.assurance.status !== "settled") {
+    if (options.assurance?.status === "incomplete") {
       parts.push(
         "",
-        "### 🛑 Incomplete review assurance",
+        "### ⚠️ Unsettled review passes",
+        "",
+        "The passes below failed on the reviewer's side after a bounded retry. Their paths are carried forward and re-reviewed automatically on the next run — do not change code to satisfy this section.",
         "",
         ...options.assurance.reasons.map((reason) => `- ${reason}`),
       );
@@ -613,14 +600,16 @@ export const planPublication = (
     options.carriedFindings ?? [],
     options.carriedConcerns ?? [],
   );
+  // Machinery gaps (incomplete input or unsettled passes) block APPROVE but
+  // never REQUEST_CHANGES: requesting changes for a reviewer-side fault would
+  // tell the author to edit code nobody reviewed.
+  const unclean =
+    options.inputCoverage?.status === "incomplete" || options.assurance?.status === "incomplete";
   const event: ReviewEvent = !options.applyVerdict
     ? "COMMENT"
-    : options.inputCoverage?.status === "incomplete" ||
-        (options.inputCoverage === undefined && options.coverage?.status === "incomplete") ||
-        (options.assurance !== undefined && options.assurance.status !== "settled") ||
-        counts.blocking > 0
+    : counts.blocking > 0
       ? "REQUEST_CHANGES"
-      : review.verdict === "approve" && counts.important === 0
+      : review.verdict === "approve" && counts.important === 0 && !unclean
         ? "APPROVE"
         : "COMMENT";
 

package/src/internal/retirement.ts

@@ -102,8 +102,10 @@ const findingIdentity = (finding: {
 
 const REVIEW_METADATA_PATTERN = /<!-- effect-agent-pr-review metadata\n[\s\S]*?\n-->/g;
 const FINGERPRINT_PATTERN = /<!-- effect-agent-pr-review fingerprint=sha256:[0-9a-f]{64} -->/g;
+// Version-agnostic on purpose: retirement only RECOGNIZES machine markers to
+// keep them byte-identical through an edit; it never authenticates them.
 const STATE_PATTERN =
-  /<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->/g;
+  /<!-- effect-agent-pr-review state-v\d+:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->/g;
 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(