@effect-agent/pr-review 0.0.1-beta.0 → 0.1.0-beta.10

package/src/internal/github.ts

@@ -1,10 +1,16 @@
 import type { Redacted } from "effect";
-import { Context, Effect, Layer, Option, Schema } from "effect";
+import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 
 import { ChangedFile } from "./diff.ts";
 import { extractFingerprint } from "./fingerprint.ts";
 import type { ReviewPublicationPlan } from "./render.ts";
+import {
+  RetirableReview,
+  RetirableReviewComment,
+  ReviewRetirementFailure,
+  ReviewRetirementHost,
+} from "./retirement.ts";
 import {
   ReviewHeadComparison,
   ReviewStateAuthenticator,
@@ -27,26 +33,46 @@ import {
 // GitHubApiFailure instead of an untyped defect.
 // ---------------------------------------------------------------------------
 
+const defaultGraphqlUrl = (apiUrl: string): string =>
+  apiUrl === "https://api.github.com"
+    ? "https://api.github.com/graphql"
+    : apiUrl.replace(/\/api\/v3$/, "/api/graphql");
+
 /** Which pull request to review and how to reach the API. */
+export const DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN = "github-actions[bot]";
+
 export class GitHubReviewTarget extends Context.Service<
   GitHubReviewTarget,
   {
     /** API root, e.g. `https://api.github.com` (no trailing slash). */
     readonly apiUrl: string;
+    /** GraphQL root, e.g. `https://api.github.com/graphql`. */
+    readonly graphqlUrl: string;
     /** `owner/name`. */
     readonly repository: string;
     readonly number: number;
     /** Absent token means unauthenticated reads (public repositories only). */
     readonly token: Option.Option<Redacted.Redacted<string>>;
+    /** Bot login expected to author reviews posted with this target's token. */
+    readonly reviewAuthorLogin?: string | undefined;
   }
 >()("@effect-agent/pr-review/GitHubReviewTarget") {
   static layer(config: {
     readonly apiUrl: string;
+    readonly graphqlUrl?: string | undefined;
     readonly repository: string;
     readonly number: number;
     readonly token: Option.Option<Redacted.Redacted<string>>;
+    readonly reviewAuthorLogin?: string | undefined;
   }): Layer.Layer<GitHubReviewTarget> {
-    return Layer.succeed(this, GitHubReviewTarget.of(config));
+    return Layer.succeed(
+      this,
+      GitHubReviewTarget.of({
+        ...config,
+        graphqlUrl: config.graphqlUrl ?? defaultGraphqlUrl(config.apiUrl),
+        reviewAuthorLogin: config.reviewAuthorLogin ?? DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN,
+      }),
+    );
   }
 }
 
@@ -82,11 +108,54 @@ const GitHubFileWire = Schema.Struct({
 
 const GitHubFilesPageWire = Schema.Array(GitHubFileWire);
 
+const GitHubActorWire = Schema.Struct({ node_id: Schema.String });
+
 const GitHubReviewWire = Schema.Struct({
   id: Schema.Int,
   html_url: Schema.String,
+  user: Schema.NullOr(GitHubActorWire),
+  submitted_at: Schema.NullOr(Schema.String),
+});
+
+const GitHubRetirableReviewWire = Schema.Struct({
+  id: Schema.Int,
+  body: Schema.NullOr(Schema.String),
+  commit_id: Schema.String,
+  user: Schema.NullOr(GitHubActorWire),
+  submitted_at: Schema.NullOr(Schema.String),
+});
+const GitHubRetirableReviewsPageWire = Schema.Array(GitHubRetirableReviewWire);
+
+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),
+  start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  original_start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+});
+const GitHubReviewCommentsPageWire = Schema.Array(GitHubReviewCommentWire);
+
+const GitHubMinimizeCommentWire = Schema.Struct({
+  data: Schema.optionalKey(
+    Schema.NullOr(
+      Schema.Struct({
+        minimizeComment: Schema.NullOr(
+          Schema.Struct({
+            minimizedComment: Schema.NullOr(Schema.Struct({ isMinimized: Schema.Boolean })),
+          }),
+        ),
+      }),
+    ),
+  ),
+  errors: Schema.optionalKey(Schema.Array(Schema.Struct({ message: Schema.String }))),
 });
 
+/** Decode GitHub's external timestamp before it participates in mutation ordering. */
+export const parseGitHubSubmittedAt = (value: string | null): DateTime.Utc | null =>
+  value === null ? null : Option.getOrNull(DateTime.make(value));
+
 /** The publication receipt callers report back to the operator. */
 export class PublishedReview extends Schema.Class<PublishedReview>(
   "@effect-agent/pr-review/PublishedReview",
@@ -95,6 +164,9 @@ export class PublishedReview extends Schema.Class<PublishedReview>(
   url: Schema.String,
   event: Schema.String,
   inlineComments: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /** Actor and ordering boundary returned by the create-review response. */
+  authorNodeId: Schema.NullOr(Schema.NonEmptyString.check(Schema.isMaxLength(200))),
+  submittedAt: Schema.NullOr(Schema.DateTimeUtc),
 }) {}
 
 /** Posts one planned review; the ONLY mutating operation in this package. */
@@ -335,12 +407,176 @@ export const gitHubReviewPublisherLayer: Layer.Layer<
             url: wire.html_url,
             event: plan.event,
             inlineComments: plan.comments.length,
+            authorNodeId: wire.user?.node_id ?? null,
+            submittedAt: parseGitHubSubmittedAt(wire.submitted_at),
           });
         }),
     });
   }),
 );
 
+// --- Live ReviewRetirementHost ----------------------------------------------
+
+const MAX_RETIREMENT_PAGES = 5;
+const MINIMIZE_REVIEW_COMMENT_MUTATION = `mutation MinimizeReviewComment($subjectId: ID!) {
+  minimizeComment(input: { subjectId: $subjectId, classifier: OUTDATED }) {
+    minimizedComment { isMinimized }
+  }
+}`;
+
+/** GitHub-backed host operations for cosmetic retirement after publication. */
+export const gitHubReviewRetirementHostLayer: Layer.Layer<
+  ReviewRetirementHost,
+  never,
+  GitHubReviewTarget | HttpClient.HttpClient
+> = Layer.effect(ReviewRetirementHost)(
+  Effect.gen(function* () {
+    const target = yield* GitHubReviewTarget;
+    const client = yield* HttpClient.HttpClient;
+    const prefix = `${target.apiUrl}/repos/${target.repository}/pulls/${target.number}`;
+    const asRetirementFailure =
+      (operation: string) =>
+      (error: { readonly _tag: string; readonly message?: string }): ReviewRetirementFailure =>
+        ReviewRetirementFailure.make({
+          operation,
+          reason: `${error._tag}: ${error.message ?? "request failed"}`.slice(0, 2_048),
+        });
+    const executeRetirement = (operation: string, request: HttpClientRequest.HttpClientRequest) =>
+      HttpClient.execute(request).pipe(
+        Effect.flatMap(HttpClientResponse.filterStatusOk),
+        Effect.mapError(asRetirementFailure(operation)),
+        Effect.provideService(HttpClient.HttpClient, client),
+      );
+    const decodeRetirement = <S extends Schema.Top>(schema: S, operation: string) => {
+      const decode = Schema.decodeUnknownEffect(schema);
+      return (response: HttpClientResponse.HttpClientResponse) =>
+        response.json.pipe(
+          Effect.mapError(asRetirementFailure(operation)),
+          Effect.flatMap((body) =>
+            decode(body).pipe(Effect.mapError(asRetirementFailure(operation))),
+          ),
+        );
+    };
+    const listPaged = <A>(input: {
+      readonly operation: string;
+      readonly url: string;
+      readonly decode: (
+        response: HttpClientResponse.HttpClientResponse,
+      ) => Effect.Effect<ReadonlyArray<A>, ReviewRetirementFailure>;
+    }) =>
+      Effect.gen(function* () {
+        const values: Array<A> = [];
+        const perPage = 100;
+        for (let page = 1; page <= MAX_RETIREMENT_PAGES; page += 1) {
+          const response = yield* executeRetirement(
+            input.operation,
+            withCommonHeaders(
+              HttpClientRequest.get(input.url).pipe(
+                HttpClientRequest.acceptJson,
+                HttpClientRequest.setUrlParams({
+                  per_page: String(perPage),
+                  page: String(page),
+                }),
+              ),
+              target.token,
+            ),
+          );
+          const pageValues = yield* input.decode(response);
+          values.push(...pageValues);
+          if (pageValues.length < perPage) return values;
+        }
+        return yield* ReviewRetirementFailure.make({
+          operation: input.operation,
+          reason: `history exceeds the bounded ${MAX_RETIREMENT_PAGES * 100}-item lookup`,
+        });
+      });
+
+    return ReviewRetirementHost.of({
+      listReviews: listPaged({
+        operation: "listReviewsForRetirement",
+        url: `${prefix}/reviews`,
+        decode: decodeRetirement(GitHubRetirableReviewsPageWire, "listReviewsForRetirement"),
+      }).pipe(
+        Effect.map((reviews) =>
+          reviews.map((review) =>
+            RetirableReview.make({
+              reviewId: review.id,
+              body: review.body ?? "",
+              commitSha: review.commit_id,
+              authorNodeId: review.user?.node_id ?? null,
+              submittedAt: parseGitHubSubmittedAt(review.submitted_at),
+            }),
+          ),
+        ),
+      ),
+      listComments: (reviewId) =>
+        listPaged({
+          operation: "listReviewCommentsForRetirement",
+          url: `${prefix}/reviews/${reviewId}/comments`,
+          decode: decodeRetirement(GitHubReviewCommentsPageWire, "listReviewCommentsForRetirement"),
+        }).pipe(
+          Effect.map((comments) =>
+            comments.map((comment) => {
+              const endLine = comment.line ?? comment.original_line;
+              const startLine = comment.start_line ?? comment.original_start_line ?? endLine;
+              return RetirableReviewComment.make({
+                nodeId: comment.node_id,
+                path: comment.path,
+                startLine,
+                endLine,
+                body: comment.body,
+              });
+            }),
+          ),
+        ),
+      updateBody: (reviewId, body) =>
+        executeRetirement(
+          "updateReview",
+          withCommonHeaders(
+            HttpClientRequest.put(`${prefix}/reviews/${reviewId}`).pipe(
+              HttpClientRequest.acceptJson,
+              HttpClientRequest.bodyJsonUnsafe({ body }),
+            ),
+            target.token,
+          ),
+        ).pipe(Effect.asVoid),
+      minimizeComment: (nodeId) =>
+        Effect.gen(function* () {
+          const response = yield* executeRetirement(
+            "minimizeComment",
+            withCommonHeaders(
+              HttpClientRequest.post(target.graphqlUrl).pipe(
+                HttpClientRequest.acceptJson,
+                HttpClientRequest.bodyJsonUnsafe({
+                  query: MINIMIZE_REVIEW_COMMENT_MUTATION,
+                  variables: { subjectId: nodeId },
+                }),
+              ),
+              target.token,
+            ),
+          );
+          const wire = yield* decodeRetirement(
+            GitHubMinimizeCommentWire,
+            "minimizeComment",
+          )(response);
+          if (
+            (wire.errors?.length ?? 0) > 0 ||
+            wire.data?.minimizeComment?.minimizedComment?.isMinimized !== true
+          ) {
+            return yield* ReviewRetirementFailure.make({
+              operation: "minimizeComment",
+              reason:
+                wire.errors
+                  ?.map((error) => error.message)
+                  .join("; ")
+                  .slice(0, 2_048) ?? "GitHub did not confirm comment minimization",
+            });
+          }
+        }),
+    });
+  }),
+);
+
 // --- Prior reviews (fingerprint deduplication) ---------------------------------
 
 /** Reading the pull request's previously posted reviews failed. */
@@ -412,6 +648,7 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
     const target = yield* GitHubReviewTarget;
     const client = yield* HttpClient.HttpClient;
     const prefix = `${target.apiUrl}/repos/${target.repository}/pulls/${target.number}`;
+    const reviewAuthorLogin = target.reviewAuthorLogin ?? DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN;
     const decodePage = Schema.decodeUnknownEffect(GitHubPriorReviewsPageWire);
     const asLookupFailure = (error: { readonly _tag: string; readonly message?: string }) =>
       PriorReviewLookupFailure.make({
@@ -443,10 +680,16 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
             Effect.flatMap((body) => decodePage(body).pipe(Effect.mapError(asLookupFailure))),
           );
           for (const wire of wires) {
-            // State controls what required scope may be omitted. The author gate
-            // rejects user prose; the terminal marker is additionally HMAC
-            // authenticated so another bot workflow or model text cannot forge it.
-            if (wire.user?.login !== "github-actions[bot]" || wire.user.type !== "Bot") continue;
+            // State controls what required scope may be omitted. Match the bot
+            // identity that posts with this target's token; the terminal marker
+            // is additionally HMAC authenticated so another workflow or model
+            // text cannot forge it.
+            if (
+              wire.user?.login.toLowerCase() !== reviewAuthorLogin.toLowerCase() ||
+              wire.user.type !== "Bot"
+            ) {
+              continue;
+            }
             const fingerprint = extractFingerprint(wire.body ?? "");
             if (fingerprint !== undefined) latest = Option.some(fingerprint);
             if (Option.isSome(authenticator)) {

package/src/internal/retirement.ts

@@ -0,0 +1,332 @@
+import { Context, DateTime, Effect, Option, Schema } from "effect";
+
+import {
+  ReviewStateAuthenticator,
+  type ReviewState,
+  type StoredReviewFinding,
+} from "./review-state.ts";
+
+// ---------------------------------------------------------------------------
+// Review retirement. GitHub mutations stay behind ReviewRetirementHost; this
+// module owns only deterministic identity matching, body rewriting, and the
+// fail-open orchestration that turns stale reviews into quiet history.
+// ---------------------------------------------------------------------------
+
+const PositiveLine = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** One previously posted review as observed through the retirement host. */
+export class RetirableReview extends Schema.Class<RetirableReview>(
+  "@effect-agent/pr-review/RetirableReview",
+)({
+  reviewId: Schema.Int.check(Schema.isGreaterThan(0)),
+  body: Schema.String.check(Schema.isMaxLength(60_000)),
+  commitSha: Schema.NonEmptyString.check(Schema.isMaxLength(64)),
+  authorNodeId: Schema.NullOr(Schema.NonEmptyString.check(Schema.isMaxLength(200))),
+  submittedAt: Schema.NullOr(Schema.DateTimeUtc),
+}) {}
+
+/** One inline comment attached to a previously posted review. */
+export class RetirableReviewComment extends Schema.Class<RetirableReviewComment>(
+  "@effect-agent/pr-review/RetirableReviewComment",
+)({
+  nodeId: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
+  path: Schema.NonEmptyString.check(Schema.isMaxLength(500)),
+  startLine: Schema.NullOr(PositiveLine),
+  endLine: Schema.NullOr(PositiveLine),
+  body: Schema.String.check(Schema.isMaxLength(65_536)),
+}) {}
+
+/** A GitHub retirement read or mutation failed. */
+export class ReviewRetirementFailure extends Schema.TaggedError<ReviewRetirementFailure>()(
+  "ReviewRetirementFailure",
+  {
+    operation: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message() {
+    return `Review retirement operation '${this.operation}' failed: ${this.reason}`;
+  }
+}
+
+/**
+ * Host-side GitHub operations used by retirement. Domain code never reaches
+ * into REST or GraphQL directly, and deterministic tests substitute this port.
+ */
+export class ReviewRetirementHost extends Context.Service<
+  ReviewRetirementHost,
+  {
+    readonly listReviews: Effect.Effect<ReadonlyArray<RetirableReview>, ReviewRetirementFailure>;
+    readonly listComments: (
+      reviewId: number,
+    ) => Effect.Effect<ReadonlyArray<RetirableReviewComment>, ReviewRetirementFailure>;
+    readonly updateBody: (
+      reviewId: number,
+      body: string,
+    ) => Effect.Effect<void, ReviewRetirementFailure>;
+    readonly minimizeComment: (nodeId: string) => Effect.Effect<void, ReviewRetirementFailure>;
+  }
+>()("@effect-agent/pr-review/ReviewRetirementHost") {}
+
+/** Observable cosmetic work completed by one fail-open retirement pass. */
+export class ReviewRetirementReport extends Schema.Class<ReviewRetirementReport>(
+  "@effect-agent/pr-review/ReviewRetirementReport",
+)({
+  reviewsRetired: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  findingsResolved: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  commentsMinimized: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  failures: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+}) {}
+
+export interface ReviewRetirementInput {
+  readonly currentReviewId: number;
+  readonly currentReviewUrl: string;
+  readonly currentAuthorNodeId: string;
+  readonly currentSubmittedAt: DateTime.Utc;
+  readonly currentState: ReviewState;
+}
+
+export interface ReviewRetirementDecision {
+  readonly body: string;
+  readonly resolvedFindings: ReadonlyArray<StoredReviewFinding>;
+  readonly priorFindingCount: number;
+}
+
+const findingIdentity = (finding: {
+  readonly path: string;
+  readonly startLine: number;
+  readonly endLine: number;
+  readonly title: string;
+}): string =>
+  `${finding.path}\u0000${finding.startLine}\u0000${finding.endLine}\u0000${finding.title}`;
+
+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;
+const STATE_PATTERN =
+  /<!-- effect-agent-pr-review state-v1:[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(
+  `${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 MAX_REVIEW_BODY_CHARS = 60_000;
+
+/** The host-authored metadata marker is the authority gate for any edit. */
+export const hasReviewMetadataMarker = (body: string): boolean =>
+  /<!-- effect-agent-pr-review metadata\n/.test(body);
+
+const machineComments = (body: string): ReadonlyArray<string> =>
+  Array.from(body.matchAll(MACHINE_COMMENT_PATTERN), (match) => match[0]);
+
+const originalVisibleBody = (body: string): string => {
+  const retired = RETIRED_ORIGINAL_PATTERN.exec(body)?.[1];
+  if (retired !== undefined) return retired;
+  return body.replace(MACHINE_COMMENT_PATTERN, "").trim().replace(VERDICT_CALLOUT_PATTERN, "");
+};
+
+const findingLocation = (finding: StoredReviewFinding): string =>
+  `${finding.path}:${finding.startLine}${
+    finding.endLine === finding.startLine ? "" : `-${finding.endLine}`
+  }`;
+
+const renderRetiredBody = (input: {
+  readonly priorBody: string;
+  readonly priorState: ReviewState;
+  readonly currentState: ReviewState;
+  readonly currentReviewUrl: string;
+  readonly resolvedFindings: ReadonlyArray<StoredReviewFinding>;
+}): string => {
+  const shortSha = input.currentState.reviewedHeadSha.slice(0, 7);
+  const comments = machineComments(input.priorBody);
+  const original = originalVisibleBody(input.priorBody);
+  const resolved =
+    input.resolvedFindings.length === 0
+      ? []
+      : [
+          "### Findings resolved by later review",
+          "",
+          ...input.resolvedFindings.map(
+            (finding) =>
+              `- \`${findingLocation(finding)}\` ~~${finding.title}~~ · resolved at \`${shortSha}\``,
+          ),
+          "",
+        ];
+  const prefix = [
+    `> ℹ️ Superseded — ${input.resolvedFindings.length} of ${input.priorState.unresolvedFindings.length} findings resolved at \`${shortSha}\`; see [the latest review](${input.currentReviewUrl}).`,
+    "",
+    "<details>",
+    "<summary>Previous review details</summary>",
+    "",
+    ...resolved,
+    "<!-- effect-agent-pr-review retired-original:start -->",
+  ];
+  const suffix = [
+    "<!-- effect-agent-pr-review retired-original:end -->",
+    "",
+    "</details>",
+    ...(comments.length === 0 ? [] : ["", ...comments]),
+  ];
+  const render = (visible: string) => [...prefix, visible, ...suffix].join("\n");
+  if (render(original).length <= MAX_REVIEW_BODY_CHARS) return render(original);
+  const truncationNotice = "\n\n_Original review content truncated during retirement._";
+  const budget = Math.max(0, MAX_REVIEW_BODY_CHARS - render(truncationNotice).length);
+  return render(`${original.slice(0, budget)}${truncationNotice}`);
+};
+
+/** Compute one prior review's resolved subset and deterministic retired body. */
+export const decideReviewRetirement = (input: {
+  readonly priorBody: string;
+  readonly priorState: ReviewState;
+  readonly currentState: ReviewState;
+  readonly currentReviewUrl: string;
+}): ReviewRetirementDecision => {
+  const current = new Set(input.currentState.unresolvedFindings.map(findingIdentity));
+  const resolvedFindings = input.priorState.unresolvedFindings.filter(
+    (finding) => !current.has(findingIdentity(finding)),
+  );
+  return {
+    body: renderRetiredBody({ ...input, resolvedFindings }),
+    resolvedFindings,
+    priorFindingCount: input.priorState.unresolvedFindings.length,
+  };
+};
+
+const inlineCommentIdentity = (comment: RetirableReviewComment): string | undefined => {
+  if (comment.startLine === null || comment.endLine === null) return undefined;
+  const firstLine = comment.body.split("\n", 1)[0] ?? "";
+  const title = INLINE_FINDING_TITLE_PATTERN.exec(firstLine)?.[1];
+  return title === undefined
+    ? undefined
+    : findingIdentity({
+        path: comment.path,
+        startLine: comment.startLine,
+        endLine: comment.endLine,
+        title,
+      });
+};
+
+const failOpen = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  fallback: A,
+  message: string,
+): Effect.Effect<A, never, R> =>
+  effect.pipe(
+    Effect.catch((error) =>
+      Effect.logWarning(`${message}: ${String(error)}`).pipe(Effect.as(fallback)),
+    ),
+  );
+
+const isStrictlyOlderReview = (review: RetirableReview, input: ReviewRetirementInput): boolean => {
+  if (review.submittedAt === null) return false;
+  const submittedAt = DateTime.toEpochMillis(review.submittedAt);
+  const currentSubmittedAt = DateTime.toEpochMillis(input.currentSubmittedAt);
+  return (
+    submittedAt < currentSubmittedAt ||
+    (submittedAt === currentSubmittedAt && review.reviewId < input.currentReviewId)
+  );
+};
+
+/**
+ * Retire every marker-bearing prior review against the newest posted state.
+ * Every lookup, edit, and minimization is isolated: retirement is cosmetic
+ * and can never change the run or check outcome.
+ */
+export const retireStaleReviews = Effect.fn("retireStaleReviews")(function* (
+  input: ReviewRetirementInput,
+) {
+  const host = yield* ReviewRetirementHost;
+  const authenticator = yield* ReviewStateAuthenticator;
+  if (authenticator.status !== "available") {
+    yield* Effect.logWarning(
+      "Skipping stale-review retirement because authenticated review state is unavailable.",
+    );
+    return ReviewRetirementReport.make({
+      reviewsRetired: 0,
+      findingsResolved: 0,
+      commentsMinimized: 0,
+      failures: 0,
+    });
+  }
+
+  let failures = 0;
+  let reviewsRetired = 0;
+  let findingsResolved = 0;
+  let commentsMinimized = 0;
+  const reviews = yield* failOpen(host.listReviews, undefined, "Could not list prior reviews");
+  if (reviews === undefined) {
+    return ReviewRetirementReport.make({
+      reviewsRetired,
+      findingsResolved,
+      commentsMinimized,
+      failures: 1,
+    });
+  }
+
+  for (const review of reviews) {
+    if (
+      review.authorNodeId !== input.currentAuthorNodeId ||
+      !isStrictlyOlderReview(review, input) ||
+      !hasReviewMetadataMarker(review.body)
+    ) {
+      continue;
+    }
+    const priorState = yield* failOpen(
+      authenticator.extract(review.body),
+      Option.none<ReviewState>(),
+      `Could not authenticate prior review ${review.reviewId}`,
+    );
+    if (Option.isNone(priorState)) continue;
+
+    const decision = decideReviewRetirement({
+      priorBody: review.body,
+      priorState: priorState.value,
+      currentState: input.currentState,
+      currentReviewUrl: input.currentReviewUrl,
+    });
+    const updated = yield* failOpen(
+      host.updateBody(review.reviewId, decision.body).pipe(Effect.as(true)),
+      false,
+      `Could not retire prior review ${review.reviewId}`,
+    );
+    if (updated) {
+      reviewsRetired += 1;
+      findingsResolved += decision.resolvedFindings.length;
+    } else {
+      failures += 1;
+    }
+
+    if (decision.resolvedFindings.length === 0) continue;
+    const comments = yield* failOpen(
+      host.listComments(review.reviewId),
+      undefined,
+      `Could not list inline comments for prior review ${review.reviewId}`,
+    );
+    if (comments === undefined) {
+      failures += 1;
+      continue;
+    }
+    const resolved = new Set(decision.resolvedFindings.map(findingIdentity));
+    for (const comment of comments) {
+      const identity = inlineCommentIdentity(comment);
+      if (identity === undefined || !resolved.has(identity)) continue;
+      const minimized = yield* failOpen(
+        host.minimizeComment(comment.nodeId).pipe(Effect.as(true)),
+        false,
+        `Could not minimize resolved inline comment ${comment.nodeId}`,
+      );
+      if (minimized) commentsMinimized += 1;
+      else failures += 1;
+    }
+  }
+
+  return ReviewRetirementReport.make({
+    reviewsRetired,
+    findingsResolved,
+    commentsMinimized,
+    failures,
+  });
+});

package/src/internal/review-agent.ts

@@ -360,6 +360,12 @@ export const defaultReviewPolicy = AgentPolicy.make({
   maxDuration: "8 minutes",
   toolConcurrency: 2,
   tokenBudget: 300_000,
+  // Keep enough output/summary headroom for the 200k-class provider window;
+  // tool-heavy histories prune before the engine spends a summarization call.
+  contextTokenLimit: 150_000,
+  // Budget soft landing (RUN-018): an exhausted reviewer returns its partial
+  // review on one final tool-free turn instead of failing the whole run.
+  onExhaustion: "final-answer",
 });
 
 // ---------------------------------------------------------------------------