infraweaver 0.1.0

package/src/utils/redact.ts

@@ -0,0 +1,86 @@
+/**
+ * Sink-independent secret redaction for log output.
+ *
+ * `core.setSecret()` only masks on the GitHub `actions` log sink. Every stdio MCP
+ * server runs with `setLogSink("stderr")` (stdout is the JSON-RPC channel there) and
+ * local dev prints to the console — neither is masked. So a stray `log.debug(env)`,
+ * an error that stringifies a request, or any line that merely contains a bearer would
+ * print it in cleartext on those sinks. This scrubs secret-shaped substrings from an
+ * already-formatted log line BEFORE it reaches any sink, so redaction no longer depends
+ * on which sink is active (it complements `core.setSecret`, it doesn't replace it).
+ *
+ * Two layers, applied in order:
+ *  1. Registered literals — exact values handed to {@link registerSecret} (e.g. the
+ *     minted managed-proxy token). Caught even when their shape is unusual.
+ *  2. Shape patterns — known token formats (`tmnd_`/`tmpx_` org + proxy tokens, the
+ *     GitHub `ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_` family + fine-grained PATs, Anthropic
+ *     keys, AWS access-key ids, `Bearer …` headers) plus any JSON property whose NAME
+ *     matches the sensitive-env patterns (reuses {@link isSensitiveEnvName}, so an
+ *     `{"GITHUB_TOKEN":"…"}` env dump is masked by key even if the value shape is novel).
+ */
+
+import { TOKEN_PREFIX } from "#app/brand";
+import { isSensitiveEnvName } from "#app/utils/secrets";
+
+const REDACTED = "***";
+
+// Literal secret values to scrub on sight — the sink-independent companion to
+// core.setSecret, seeded by mint/auth code that already registers with @actions/core.
+const registeredSecrets = new Set<string>();
+
+/**
+ * Register a literal secret value for sink-independent log redaction. Safe to call with
+ * any string; values under 8 chars are ignored so we never scrub a common substring.
+ * Complements `core.setSecret` (call both) — this one also masks on stderr/local sinks.
+ */
+export function registerSecret(value: string | undefined | null): void {
+  if (typeof value === "string" && value.length >= 8) registeredSecrets.add(value);
+}
+
+/** Test-only: clear the literal registry between cases. */
+export function _resetRegisteredSecrets(): void {
+  registeredSecrets.clear();
+}
+
+// Token-shaped secrets: a recognizable scheme prefix (kept, so the line still reads)
+// followed by secret material (masked). The trailing class spans the base64url/JWT
+// alphabet so dotted `tmpx_` proxy tokens are consumed whole. Anthropic `sk-ant-` is
+// included; the generic OpenAI `sk-` is deliberately NOT (too collision-prone with
+// ordinary `sk-…` slugs, and this engine routes Anthropic/Bedrock anyway).
+const TOKEN_SHAPES = new RegExp(
+  `\\b(${TOKEN_PREFIX}|tmpx_|gh[pousr]_|github_pat_|sk-ant-)[A-Za-z0-9._-]{12,}`,
+  "g",
+);
+
+// AWS access-key id (AKIA/ASIA + 16 upper-alnum) — a distinctive fixed shape.
+const AWS_ACCESS_KEY = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
+
+// `Authorization: Bearer <token>` / bare `bearer <token>` — mask the credential, keep
+// the scheme word. Catches JWTs and any bearer that the prefix patterns don't.
+const BEARER = /\b(bearer\s+)[A-Za-z0-9._-]{8,}/gi;
+
+// A JSON string property `"NAME":"VALUE"`; VALUE is masked only when NAME matches the
+// sensitive-env patterns. Tolerates escaped quotes inside the value.
+const JSON_STRING_PROP = /"([A-Za-z_][A-Za-z0-9_]*)"\s*:\s*"(?:[^"\\]|\\.)*"/g;
+
+/**
+ * Redact secret-shaped substrings from an already-formatted log line. Idempotent,
+ * allocation-light on the common (no-secret) path, and never throws.
+ */
+export function redactSecrets(text: string): string {
+  if (!text) return text;
+  let out = text;
+
+  for (const secret of registeredSecrets) {
+    if (out.includes(secret)) out = out.split(secret).join(REDACTED);
+  }
+
+  out = out.replace(JSON_STRING_PROP, (full, key: string) =>
+    isSensitiveEnvName(key) ? `"${key}":"${REDACTED}"` : full,
+  );
+  out = out.replace(BEARER, (_m, scheme: string) => `${scheme}${REDACTED}`);
+  out = out.replace(TOKEN_SHAPES, (_m, scheme: string) => `${scheme}${REDACTED}`);
+  out = out.replace(AWS_ACCESS_KEY, REDACTED);
+
+  return out;
+}

package/src/utils/registryAuth.ts

@@ -0,0 +1,115 @@
+/**
+ * Private Terraform registry credential pass-through (the refactor `b.4` shape).
+ *
+ * Adopting a third-party module from a PRIVATE registry — HCP Terraform
+ * (`app.terraform.io`), Terraform Enterprise, or an org's own registry — needs
+ * Terraform/OpenTofu to authenticate to that registry's host when it resolves the
+ * module during `init`. The CLI reads a per-host bearer token from the env var
+ * `TF_TOKEN_<host>` (its documented convention; equivalent to a `credentials {}`
+ * block in the CLI config). The action runs scan/init under a restricted env that
+ * strips every `*_TOKEN` so a scanner can't exfiltrate a secret — which also strips
+ * any registry token. So an operator-supplied `registry_token` is re-admitted to the
+ * terraform subprocess ONLY, per-host and ephemerally, by this module — never written
+ * to disk, never a CLI-config file, never the action's own git.
+ *
+ * Host → env-var encoding follows Terraform's rule: lower-case the host, encode each
+ * `.` as `_` and each `-` as `__` (a literal `-` is invalid in an env var name).
+ * e.g. `app.terraform.io` → `TF_TOKEN_app_terraform_io`;
+ * `private.example-registry.io` → `TF_TOKEN_private_example__registry_io`.
+ *
+ * This is the registry-protocol counterpart of moduleFetch.ts (which handles the
+ * `git::` transport); `resolveModuleCredentialEnv` below merges the two so the
+ * scan/verify/plan/equivalence paths treat both credentials identically.
+ */
+import { resolveModuleFetchEnv } from "#app/utils/moduleFetch";
+
+/** the HCP Terraform / private-registry host a `registry_token` defaults to. */
+export const DEFAULT_REGISTRY_HOST = "app.terraform.io";
+
+/**
+ * The `TF_TOKEN_<host>` env-var NAME for a registry host, per Terraform's encoding:
+ * lower-cased, each `.` → `_`, each `-` → `__`. The two replacements operate on
+ * disjoint characters, so order is immaterial. Pure.
+ */
+export function registryTokenEnvName(host: string): string {
+  const encoded = host.trim().toLowerCase().replace(/-/g, "__").replace(/\./g, "_");
+  return `TF_TOKEN_${encoded}`;
+}
+
+/**
+ * Parse the `registry_host` input (newline/comma-separated) into the hosts a
+ * registry token authorises. Blank/whitespace entries are dropped and hosts are
+ * de-duplicated case-insensitively. Falls back to the HCP host when none is given —
+ * the overwhelmingly common private-registry target — so supplying just a token works.
+ */
+export function registryHosts(raw?: string | undefined): string[] {
+  const seen = new Set<string>();
+  const hosts: string[] = [];
+  for (const part of (raw ?? "").split(/[\n,]/)) {
+    const host = part.trim().toLowerCase();
+    if (!host || seen.has(host)) continue;
+    seen.add(host);
+    hosts.push(host);
+  }
+  return hosts.length > 0 ? hosts : [DEFAULT_REGISTRY_HOST];
+}
+
+/**
+ * Build the `TF_TOKEN_<host>=<token>` env that authorises `terraform init` to fetch
+ * a private-registry module for each host. Pure (token + hosts in, env out) so it is
+ * unit-testable without a real terraform. The token only ever lands in a VALUE, never
+ * a key. Returns `{}` for a blank token or no usable host.
+ */
+export function buildRegistryTokenEnv(token: string, hosts: string[]): Record<string, string> {
+  const t = token.trim();
+  if (!t) return {};
+  const env: Record<string, string> = {};
+  for (const host of hosts) {
+    if (!host.trim()) continue;
+    env[registryTokenEnvName(host)] = t;
+  }
+  return env;
+}
+
+/**
+ * Resolve the registry-token env for a run, or undefined when no `registry_token`
+ * was supplied (the common public-registry/local case). Mirrors
+ * `resolveModuleFetchEnv` so the scan/verify/plan/refactor paths treat both
+ * credentials identically. The token authorises the hosts named in `registryHost`
+ * (default: the HCP host).
+ */
+export function resolveRegistryTokenEnv(payload: {
+  registryToken?: string | undefined;
+  registryHost?: string | undefined;
+}): Record<string, string> | undefined {
+  const token = payload.registryToken?.trim();
+  if (!token) return undefined;
+  const env = buildRegistryTokenEnv(token, registryHosts(payload.registryHost));
+  return Object.keys(env).length > 0 ? env : undefined;
+}
+
+/**
+ * The full extra-env a terraform subprocess needs to FETCH private modules: the
+ * git-transport credential for cross-repo `git::` modules (moduleFetch.ts) merged
+ * with the registry-protocol token for private-registry modules (this file). The two
+ * key namespaces (`GIT_CONFIG_*` / `GIT_SSH_COMMAND` vs `TF_TOKEN_*`) never collide.
+ * Both are scoped to the subprocess and never persisted. Returns undefined when
+ * neither is configured (the common public/local-module case). This is the single
+ * resolver the scan / verify / plan / equivalence-check paths call so they treat both
+ * credentials alike.
+ */
+export function resolveModuleCredentialEnv(
+  payload: {
+    moduleFetchToken?: string | undefined;
+    moduleFetchSshKey?: string | undefined;
+    registryToken?: string | undefined;
+    registryHost?: string | undefined;
+  },
+  opts: { sshKeyDir?: string; writeKey?: (path: string, contents: string) => void } = {},
+): Record<string, string> | undefined {
+  const env = {
+    ...resolveModuleFetchEnv(payload, opts),
+    ...resolveRegistryTokenEnv(payload),
+  };
+  return Object.keys(env).length > 0 ? env : undefined;
+}

package/src/utils/remediationCommand.ts

@@ -0,0 +1,144 @@
+/**
+ * Comment-command interface. A developer can scope a remediation run from
+ * a PR/issue comment that mentions the bot:
+ *
+ *   @infraweaver fix #3a9f1c2          → fix exactly one concern (by id or short id)
+ *   @infraweaver fix all high-severity → fix every concern at/above a severity
+ *   @infraweaver fix all               → fix everything (still bounded by max_prs)
+ *   @infraweaver fix main.tf           → fix one file's group
+ *
+ * Propose, then let me steer — when a non-trivial finding has several
+ * genuinely distinct valid fixes, Remediate proposes 2–3 labelled strategies in
+ * a comment instead of guessing, and the reviewer picks one by replying:
+ *
+ *   @infraweaver fix #3a9f1c2 with strategy B   → apply strategy B to that concern
+ *   @infraweaver strategy 2                      → pick strategy 2 (concern from the thread)
+ *
+ * The parsing is pure + deterministic so the scoping doesn't depend on the
+ * model's reading of the comment. The Remediate mode applies the parsed scope
+ * (which group(s) to act on, and which strategy) instead of the default
+ * "highest-severity group, agent's-choice fix".
+ */
+
+import { COMMENT_COMMAND } from "#app/brand";
+
+export type RemediationCommand =
+  | { kind: "concern"; concernRef: string; strategy?: string }
+  | { kind: "severity"; severity: Severity }
+  | { kind: "file"; file: string }
+  // bulk remediation — sweep ONE scanner rule across every file it fires in
+  // (one coherent PR via by-rule grouping). e.g. `@infraweaver fix rule CKV_AWS_23`.
+  | { kind: "rule"; ruleId: string }
+  // a bare strategy pick (e.g. an in-thread reply to a proposal); the
+  // concern is resolved from the comment thread the run was triggered on.
+  | { kind: "strategy"; strategy: string }
+  | { kind: "all" };
+
+const SEVERITIES = ["critical", "high", "medium", "low", "info"] as const;
+type Severity = (typeof SEVERITIES)[number];
+
+/** the bot handles a mention can use (with or without the `[bot]` suffix). */
+const MENTION = new RegExp(`${COMMENT_COMMAND}(?:\\[bot\\])?\\b`, "i");
+
+/**
+ * the canonical phrasing the proposal comment must tell reviewers to reply
+ * with. Lives next to the parser that accepts it so the proposal template (in
+ * the Remediate prompt) and the parser can never drift apart. `<concern-id>` and
+ * `<A|B|C>` are placeholders the agent fills with the real id and the offered
+ * strategy labels.
+ */
+export const STRATEGY_REPLY_HINT = `${COMMENT_COMMAND} fix #<concern-id> with strategy <A|B|C>`;
+
+// a strategy label is a single letter (A–Z, normalised to upper) or digit (1–9),
+// introduced by `strategy` / `option` / `approach`. The single-char + `\b` bound
+// keeps it off prose ("a good strategy overall" has no single-char boundary).
+const STRATEGY = /\b(?:strategy|option|approach)\s+#?([A-Za-z]|[1-9])\b/i;
+
+function parseStrategyToken(text: string): string | undefined {
+  // the capture is a single required char, so guarding `?.[1]` is equivalent to
+  // the old `m[1]!` but carries the non-null in the type rather than an assertion.
+  const tok = text.match(STRATEGY)?.[1];
+  if (!tok) return undefined;
+  return /[A-Za-z]/.test(tok) ? tok.toUpperCase() : tok;
+}
+
+/**
+ * Parse a `@infraweaver fix …` command out of a comment body. Returns null when
+ * the body isn't a recognised fix command (the run then falls back to its
+ * default scope). Tolerant of surrounding prose — it scans for the mention then
+ * the `fix` verb and its argument.
+ */
+export function parseRemediationCommand(
+  body: string | undefined,
+): RemediationCommand | null {
+  if (!body) return null;
+  if (!MENTION.test(body)) return null;
+
+  // everything after the mention; we keep original case for the file/concern-ref
+  // capture (the lower-casing happens per match).
+  const afterMention = body.slice(body.search(MENTION));
+  const isSeverity = (s: string): s is Severity =>
+    (SEVERITIES as readonly string[]).includes(s);
+
+  // bulk — `fix rule <rule-id>` / `fix all rule <rule-id>`. Checked FIRST and
+  // gated on the explicit `rule` keyword so a scanner rule id (`CKV_AWS_23`,
+  // `terraform_required_version`, `trivy:AVD-AWS-0088`) is never confused with a
+  // severity word, a filename, or a hex concern id. Rule ids are case-significant
+  // — kept verbatim. The fix sweeps that ONE rule across every file it fires in.
+  const ruleId = afterMention.match(
+    /\bfix\s+(?:all\s+)?rule\s+([A-Za-z][A-Za-z0-9_.:-]+)\b/i,
+  )?.[1];
+  if (ruleId) return { kind: "rule", ruleId };
+
+  // `fix all <sev>[-severity]` / `fix all` — but a NON-severity word after "all"
+  // (prose like "fix all the bugs") is NOT the command: fall through rather than
+  // silently treating it as "fix everything".
+  const all = afterMention.match(
+    /\bfix\s+all\b(?:\s+([a-z]+)(?:\s*-?\s*severity)?)?/i,
+  );
+  if (all) {
+    const trailing = all[1]?.toLowerCase();
+    if (!trailing) return { kind: "all" };
+    if (isSeverity(trailing)) return { kind: "severity", severity: trailing };
+    // a non-severity word followed "all" → prose, not a command. fall through.
+  }
+
+  // `fix <sev>-severity` (without "all")
+  const sev = afterMention
+    .match(/\bfix\s+([a-z]+)\s*-?\s*severity\b/i)?.[1]
+    ?.toLowerCase();
+  if (sev && isSeverity(sev)) return { kind: "severity", severity: sev };
+
+  // `fix <path>.tf` / `fix <path>.tfvars` — a specific file's group. Checked
+  // BEFORE the concern-id form so an all-hex filename stem (e.g. `deadbeef.tf`)
+  // isn't mis-read as a concern id.
+  const file = afterMention.match(/\bfix\s+([^\s#]+\.tf(?:vars)?)\b/i)?.[1];
+  if (file) return { kind: "file", file };
+
+  // `fix #<id>` or `fix <id>` — a concern id is hex (content hash, 6–40 chars).
+  // carries an optional strategy label when the comment selects one.
+  const concernRef = afterMention
+    .match(/\bfix\s+#?([0-9a-f]{6,40})\b/i)?.[1]
+    ?.toLowerCase();
+  if (concernRef) {
+    const strategy = parseStrategyToken(afterMention);
+    return strategy
+      ? { kind: "concern", concernRef, strategy }
+      : { kind: "concern", concernRef };
+  }
+
+  // a strategy pick with no `fix` verb (e.g. an in-thread reply). If the
+  // reviewer still named a `#<id>`, keep it as a scoped concern; otherwise the
+  // concern is resolved from the thread the comment lives on.
+  const strategy = parseStrategyToken(afterMention);
+  if (strategy) {
+    const concernRef = afterMention
+      .match(/#([0-9a-f]{6,40})\b/i)?.[1]
+      ?.toLowerCase();
+    return concernRef
+      ? { kind: "concern", concernRef, strategy }
+      : { kind: "strategy", strategy };
+  }
+
+  return null;
+}

package/src/utils/retry.ts

@@ -0,0 +1,180 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { log } from "#app/utils/cli";
+
+/** Default upper bound on a honored server Retry-After hint (ms). A hostile or
+ *  buggy `Retry-After` could otherwise stall a run for its full value (GitHub
+ *  secondary-rate-limit responses have carried multi-minute hints); 20s matches
+ *  octokit's throttling-plugin ceiling. */
+export const DEFAULT_RETRY_AFTER_CAP_MS = 20_000;
+
+export type RetryOptions = {
+  maxAttempts?: number;
+  delayMs?: number;
+  /**
+   * explicit delay schedule — one entry per retry (length N ⇒ N+1 attempts).
+   * when set, overrides `maxAttempts` and `delayMs`. e.g. `[1_000, 3_000]`
+   * means up to 3 attempts, sleeping 1s before retry 2 and 3s before retry 3.
+   */
+  delaysMs?: readonly number[];
+  shouldRetry?: (error: unknown) => boolean;
+  /** cap (ms) on a honored server Retry-After / rate-limit-reset hint. default
+   *  {@link DEFAULT_RETRY_AFTER_CAP_MS}. The fixed backoff is never capped —
+   *  this only bounds how long a *server-suggested* delay can extend it. */
+  retryAfterCapMs?: number;
+  label?: string;
+};
+
+/** A numeric HTTP status carried on an error (some clients set `.status`/`.statusCode`). */
+function statusOf(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const e = error as { status?: unknown; statusCode?: unknown };
+  if (typeof e.status === "number") return e.status;
+  if (typeof e.statusCode === "number") return e.statusCode;
+  return undefined;
+}
+
+/**
+ * A broad transient predicate for octokit/GitHub calls: an HTTP 5xx (an upstream
+ * blip) OR a network-class error. Distinct from a deterministic 4xx (404/401/403/
+ * 422), which fails fast. Pass as `shouldRetry` for idempotent GitHub reads/
+ * dispatches whose client carries no 5xx retry of its own (mirrors pullfrog's
+ * `isTransientOctokitError`). see #999/#997.
+ */
+export function isTransientServerError(error: unknown): boolean {
+  const status = statusOf(error);
+  if (status !== undefined) return status >= 500;
+  if (!(error instanceof Error)) return false;
+  return (
+    error.name === "AbortError" ||
+    error.message.includes("fetch failed") ||
+    error.message.includes("ECONNRESET") ||
+    error.message.includes("ETIMEDOUT")
+  );
+}
+
+/** Response headers hung off a thrown HTTP error (octokit sets `error.response.headers`). */
+function errorResponseHeaders(error: unknown): Record<string, unknown> | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const response = (error as { response?: unknown }).response;
+  if (typeof response !== "object" || response === null) return undefined;
+  const headers = (response as { headers?: unknown }).headers;
+  if (typeof headers !== "object" || headers === null) return undefined;
+  return headers as Record<string, unknown>;
+}
+
+/**
+ * A server-suggested retry delay in ms, resolved from (in order):
+ *   1. an explicit `retryAfterMs` property a caller stashed on the error (e.g.
+ *      {@link parseRetryAfter} off a `Response`);
+ *   2. the `retry-after` response header (RFC-9110 delta-seconds / HTTP-date) —
+ *      an explicit backoff directive whenever present (covers secondary rate
+ *      limits, which carry it with `x-ratelimit-remaining > 0`);
+ *   3. `x-ratelimit-reset` (epoch seconds) but ONLY when `x-ratelimit-remaining`
+ *      is `"0"` — GitHub returns the reset header on ~every response (~1h ahead),
+ *      so honoring it unconditionally would balloon EVERY retried error (even a
+ *      permissions 403) to the cap. Gating on real exhaustion matches octokit's
+ *      throttling plugin.
+ * Returns `undefined` when no applicable hint is present/parseable.
+ */
+function retryAfterMsOf(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const r = (error as { retryAfterMs?: unknown }).retryAfterMs;
+  if (typeof r === "number" && Number.isFinite(r) && r >= 0) return r;
+
+  const headers = errorResponseHeaders(error);
+  if (!headers) return undefined;
+  const retryAfter = headers["retry-after"];
+  if (typeof retryAfter === "string" && retryAfter.trim() !== "") {
+    const parsed = parseRetryAfter(retryAfter);
+    if (parsed !== undefined) return parsed;
+  }
+  if (headers["x-ratelimit-remaining"] === "0") {
+    const reset = headers["x-ratelimit-reset"];
+    if (typeof reset === "string" && reset.trim() !== "") {
+      const resetEpoch = Number(reset);
+      if (Number.isFinite(resetEpoch)) return Math.max(0, resetEpoch * 1000 - Date.now());
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Parse an HTTP `Retry-After` header value into milliseconds. Accepts the two
+ * RFC-9110 forms — delta-seconds (`"120"`) and an HTTP-date (`"Wed, 21 Oct 2026
+ * 07:28:00 GMT"`) — and returns `undefined` for anything else. Callers that hold
+ * the `Response` attach the result as `retryAfterMs` on the thrown error so
+ * {@link retry} can floor its backoff to it.
+ */
+export function parseRetryAfter(
+  value: string | null | undefined,
+): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1000;
+  const at = Date.parse(trimmed);
+  if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
+  return undefined;
+}
+
+// Statuses worth retrying: rate-limit (429) + transient server errors (502/503/504).
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+
+const defaultShouldRetry = (error: unknown): boolean => {
+  const status = statusOf(error);
+  if (status !== undefined && RETRYABLE_STATUSES.has(status)) return true;
+  if (!(error instanceof Error)) return false;
+  return (
+    error.name === "AbortError" ||
+    error.message.includes("fetch failed") ||
+    error.message.includes("ECONNRESET") ||
+    error.message.includes("ETIMEDOUT") ||
+    /\b(429|502|503|504)\b/.test(error.message)
+  );
+};
+
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+  const label = options.label ?? "operation";
+  const delays = options.delaysMs
+    ? Array.from(options.delaysMs)
+    : Array.from(
+        { length: (options.maxAttempts ?? 3) - 1 },
+        (_, i) => (options.delayMs ?? 1000) * (i + 1),
+      );
+  const maxAttempts = delays.length + 1;
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxAttempts || !shouldRetry(error)) {
+        throw error;
+      }
+
+      const scheduled = delays[attempt - 1] ?? options.delayMs ?? 1000;
+      const serverDelay = retryAfterMsOf(error);
+      // cap the server hint first, then floor at the fixed delay — so a hint
+      // never shortens below `scheduled`, and an overlong one can't hang the
+      // run. the fixed backoff itself is never capped.
+      const cap = options.retryAfterCapMs ?? DEFAULT_RETRY_AFTER_CAP_MS;
+      const base =
+        serverDelay !== undefined
+          ? Math.max(scheduled, Math.min(cap, serverDelay))
+          : scheduled;
+      const delay = Math.round(base + Math.random() * base * 0.5);
+      log.info(
+        `» ${label} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delay}ms...`,
+      );
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}

package/src/utils/reviewCleanup.ts

@@ -0,0 +1,116 @@
+import { PRODUCT_SLUG } from "#app/brand";
+import type { WriteablePayload } from "#app/external";
+import { reportReviewNodeId } from "#app/mcp/review";
+import type { ToolContext } from "#app/mcp/server";
+import { log } from "#app/utils/cli";
+
+const RE_REVIEW_PREAMBLE =
+  "Incrementally re-review the new commits on this pull request. Use the IncrementalReview mode.";
+
+/**
+ * post-agent review lifecycle: runs after the agent exits (success or timeout).
+ *
+ * normally the agent handles new commits inline: create_pull_request_review
+ * detects HEAD movement and tells the agent to pull and review the delta.
+ * this dispatch is a safety net for cases where the agent couldn't handle
+ * it (timeout, error, etc).
+ *
+ * ordering matters: reportReviewNodeId marks this run "done" FIRST so push
+ * webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
+ * catch any pushes that were suppressed while this run was in-flight.
+ */
+export async function postReviewCleanup(ctx: ToolContext): Promise<void> {
+  const review = ctx.toolState.review;
+  if (!review) return;
+  delete ctx.toolState.review;
+
+  // mark review as submitted — unlocks webhook dedup for new pushes
+  await bestEffort(
+    () => reportReviewNodeId(ctx, { nodeId: review.nodeId }),
+    "reportReviewNodeId",
+  );
+
+  // dispatch follow-up if PR HEAD moved past the reviewed commit
+  if (review.reviewedSha) {
+    await bestEffort(
+      () => dispatchFollowUpReReview(ctx, review.reviewedSha!),
+      "follow-up re-review dispatch",
+    );
+  }
+}
+
+async function bestEffort(
+  fn: () => Promise<unknown>,
+  label: string,
+): Promise<void> {
+  try {
+    await fn();
+  } catch (error) {
+    log.debug(`${label} failed: ${error}`);
+  }
+}
+
+async function dispatchFollowUpReReview(
+  ctx: ToolContext,
+  reviewedSha: string,
+): Promise<void> {
+  const issueNumber = ctx.payload.event.issue_number;
+  if (!issueNumber) return;
+
+  const pr = await ctx.octokit.rest.pulls.get({
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    pull_number: issueNumber,
+  });
+
+  if (pr.data.head.sha === reviewedSha) return;
+  if (pr.data.state !== "open") return;
+  if (pr.data.draft) return;
+
+  log.info(
+    `safety net: pr HEAD moved from ${reviewedSha.slice(0, 7)} to ${pr.data.head.sha.slice(0, 7)} ` +
+      `and agent did not review inline — dispatching follow-up re-review`,
+  );
+
+  const event: WriteablePayload["event"] = {
+    trigger: "pull_request_synchronize",
+    issue_number: issueNumber,
+    is_pr: true,
+    title: pr.data.title,
+    body: null,
+    branch: pr.data.head.ref,
+    before_sha: reviewedSha,
+    silent: true,
+  };
+  if (ctx.payload.event.authorPermission) {
+    event.authorPermission = ctx.payload.event.authorPermission;
+  }
+
+  const payload: WriteablePayload = {
+    "~infraweaver": true,
+    version: ctx.payload.version,
+    model: ctx.payload.model,
+    prompt: "",
+    eventInstructions: RE_REVIEW_PREAMBLE,
+    event,
+  };
+
+  await ctx.octokit.rest.actions.createWorkflowDispatch({
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    workflow_id: getCurrentWorkflowFilename(),
+    ref: pr.data.base.repo.default_branch,
+    inputs: { prompt: JSON.stringify(payload) },
+  });
+}
+
+/**
+ * derive the running workflow's filename from `GITHUB_WORKFLOW_REF`, which has the form
+ * `<owner>/<repo>/.github/workflows/<filename>@<ref>` (e.g. `.../infraweaver.yaml@refs/heads/main`).
+ * falls back to `infraweaver.yml` if the env var is missing or malformed (shouldn't happen in CI).
+ */
+function getCurrentWorkflowFilename(): string {
+  const ref = process.env.GITHUB_WORKFLOW_REF ?? "";
+  const match = ref.match(/\/([^/]+)@/);
+  return match?.[1] ?? `${PRODUCT_SLUG}.yml`;
+}