autoforge-cli 0.1.0a0__py3-none-any.whl

autoforge/redaction.py

@@ -0,0 +1,408 @@
+"""Secret redaction for anything that lands in logs.
+
+Baseline protection only — no detector claims to catch every secret shape.
+Covers common env-var assignments, ``Authorization`` headers, well-known
+token shapes (GitHub PATs, OpenAI / Anthropic keys, Google API keys, JWTs),
+OAuth credential fields (``refresh`` / ``access`` / ``id_token`` /
+``chatgpt-account-id``) and credentials embedded in URLs before stdout /
+stderr / commands are persisted by the run logger. A shape is recognised
+where it starts a token: at the start of the text, after a character that
+cannot be part of it, or directly after an escape sequence (``ESC[0m``,
+``\\n``, ``\\u00e9``; see ``_ESCAPE``). An assignment's quoted value is
+recognised behind an escaped quote too (``GH_TOKEN=\\"...\\"``, as JSON
+writes it; see ``_QUOTE``).
+
+Every pattern has a stable class name. :func:`credential_classes` reports
+which classes a text carries without saying where, so a refusal of agent
+text that would be published (``result_parser``'s content policy) can name
+what to remove without quoting the secret.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+
+class _Pattern(NamedTuple):
+    """One secret shape: its stable class name, the regexes and the replacements.
+
+    ``regex`` finds the shape and ``replacement`` rewrites it. A shape that
+    starts a token (:func:`_token`) has a second pass, ``after_escape``,
+    which finds it directly after an escape sequence and keeps that sequence
+    through ``escape_replacement``; the others have none.
+    """
+
+    name: str
+    regex: re.Pattern[str]
+    replacement: str
+    after_escape: re.Pattern[str] | None = None
+    escape_replacement: str = ""
+
+
+# Where a recognised credential may start (#284). There is no regex word
+# boundary (``\b``) after the ``m`` of an ANSI colour code (``ESC[0m``, which
+# OpenCode writes right before an error's text on stderr) or after the ``n``
+# of a ``\n`` written out as two characters (JSON text, a C or Python string
+# literal): both are word characters, so a token directly after one was
+# missed. A token therefore starts at the start of the text, after any
+# character that cannot be part of it (any but an ASCII letter, a digit or
+# ``_``, unless a pattern names its own set; a non-ASCII letter is no part of
+# an ASCII token), or directly after one of these escape sequences:
+#
+# - an ANSI / VT escape sequence: a CSI (``ESC[``, or the C1 byte, then
+#   parameter, intermediate and final bytes) or a two-character escape
+#   (``ESC(B``, ``ESC7``), its ESC also as JSON, C, a shell and caret
+#   notation spell it (``\u001b``, ``\x1b``, ``\033``, ``\e``, ``^[``); an OSC
+#   or DCS string ends in BEL or ``ESC\``, already no token character;
+# - a backslash escape as JSON, C and Python write one: a single letter
+#   (``\n``, ``\t``, ``\b``, ...), ``\xHH``, ``\uHHHH``, ``\UHHHHHHHH`` and octal.
+#
+# A backslash and such a letter count as an escape wherever they occur, a
+# path separator before a token included (``C:\Users\nghp_...``): the rule
+# errs on redacting. Only the escape right before a token matters, so a run
+# of them (``ESC[91mESC[1m``) needs nothing more. The escapes are matched
+# case-sensitively inside a ``(?i)`` pattern too: ``\N`` is no escape.
+#
+# Each alternative below starts with its literal ESC, backslash, caret or C1
+# byte, so the regex engine scans for those characters and tries an
+# ``after_escape`` pass nowhere else: on text with few of them the second
+# pass costs a fraction of the first, and each candidate scans one escape,
+# so both stay linear.
+_ESCAPE_TAIL = r"(?:\[[0-?]*[ -/]*[@-~]|[ -/]*[0-~])"
+_ESCAPE = (
+    r"(?-i:"
+    rf"\x1b{_ESCAPE_TAIL}"
+    rf"|\\(?:(?:u001[bB]|U0000001[bB]|x1[bB]|0?33|e){_ESCAPE_TAIL}"
+    r"|[abefnrtv]|x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8}|[0-7]{1,3})"
+    rf"|\^\[{_ESCAPE_TAIL}"
+    r"|\x9b[0-?]*[ -/]*[@-~]"
+    r")"
+)
+
+
+# The optional quote around an assignment's value, also as escaped text
+# writes it (#281): JSON and a C or Python string literal write a quote as
+# ``\"`` or ``\'``, so in a serialized document (an agent's CONTROL_RESULT on
+# stdout, a structure printed as JSON) ``GH_TOKEN="..."`` reads
+# ``GH_TOKEN=\"...\"``. A plain quote alone stopped the value at the
+# backslash and left the secret after it in the clear. Up to seven
+# backslashes (JSON carried in a JSON string, three deep) are taken with the
+# quote, the bound ``oauth-field`` uses, so a run of them is never rescanned.
+_QUOTE = r"(?:\\{0,7}[\"'])?"
+# A backslash inside an assignment's value, unless it starts the escaped
+# closing quote, which is kept in its own group with the backslashes before
+# it: the replacement leaves ``\"`` whole and the JSON around it intact. The
+# lookahead is bounded like ``_QUOTE``.
+_VALUE_BACKSLASH = r"\\(?!\\{0,6}[\"'])"
+
+
+def _token(
+    name: str, body: str, replacement: str, *, flags: str = "", token_chars: str = "A-Za-z0-9_"
+) -> _Pattern:
+    """The pattern for a shape that starts a token, by the rule above.
+
+    ``regex`` finds ``body`` at the start of the text or after any character
+    but ``token_chars``. ``after_escape`` finds it directly after an escape
+    sequence, taken in as the ``lead`` group, and ``escape_replacement``
+    puts that back before ``replacement``, whose ``\\N`` references move one
+    group on past it. A new pattern is built here, never on ``\\b``.
+    """
+    return _Pattern(
+        name,
+        re.compile(rf"{flags}(?<![{token_chars}]){body}"),
+        replacement,
+        re.compile(rf"{flags}(?P<lead>{_ESCAPE}){body}"),
+        r"\g<lead>" + re.sub(r"\\(\d+)", lambda m: rf"\g<{int(m[1]) + 1}>", replacement),
+    )
+
+
+# The OAuth credential fields a quoted key names: the ``oauth-field`` pattern
+# below, and :func:`redact_obj` for a mapping entry under such a key.
+_OAUTH_FIELD_NAMES = r"refresh|access|(?:refresh|access|id)_token|chatgpt[-_]account[-_]id"
+
+# Applied in this order, each to the previous one's output, a pattern's
+# ``after_escape`` pass right after its ``regex``; the order is part of
+# :func:`redact`'s output and of the class :func:`credential_classes`
+# reports. An ``sk-ant-`` key with at least eight characters after ``sk-`` is
+# replaced by ``openai-key`` before ``anthropic-key`` sees it, so it is
+# reported under that class.
+_PATTERNS: tuple[_Pattern, ...] = (
+    # VAR=secret / VAR: secret assignments for well-known names.
+    _token(
+        "env-assignment",
+        r"(GITHUB_TOKEN|GH_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|"
+        r"OPENCODE_API_KEY|GITLAB_TOKEN|HF_TOKEN|SLACK_TOKEN|AWS_SECRET_ACCESS_KEY|"
+        r"ANTHROPIC_AUTH_TOKEN|CLAUDE_CODE_OAUTH_TOKEN|OPENCODE_SERVER_PASSWORD)"
+        rf"(\s*[:=]\s*)({_QUOTE})((?:[^\s\"';\\]|{_VALUE_BACKSLASH})+)({_QUOTE})",
+        r"\1\2\3***REDACTED***\5",
+        flags="(?i)",
+    ),
+    # Authorization: Bearer <token> / Token <token> / Basic <base64>
+    _token(
+        "authorization-header",
+        r"(Authorization\s*:\s*(?:Bearer|Token|Basic)\s+)([^\s\"';]+)",
+        r"\1***REDACTED***",
+        flags="(?i)",
+    ),
+    # Credentials embedded in a URL: everything between ``scheme://`` and
+    # ``@`` (``https://x-access-token:<token>@github.com/...``,
+    # ``https://<token>@...``, ``postgresql://user:password@...``). The whole
+    # userinfo goes, username included: a bare userinfo is as often a token
+    # as a name, and the host and path that follow keep the line readable.
+    # The userinfo class stops at the characters that end a URL's authority
+    # (``/``, ``?``, ``#``; RFC 3986 §3.2), so an ``@`` in a path, query or
+    # fragment (``https://host?to=a@b``) is not mistaken for a credential
+    # delimiter. The scheme is bounded and the class excludes ``/``, so a
+    # candidate never scans past the ``://`` of the next one: the pass stays
+    # linear over the 16 MiB an executor capture can be.
+    _token(
+        "url-userinfo",
+        r"([a-z][a-z0-9+.-]{1,31}://)[^\s/?#@]+@",
+        r"\1***REDACTED***@",
+        flags="(?i)",
+    ),
+    # JWTs: three base64url segments, the first a ``{"`` JSON header. Only
+    # the header has a floor: ``eyJ`` is ``{"`` plus the first key character,
+    # and the smallest such object (``{"a":0}``) encodes to ten characters.
+    # The payload and signature may be short or empty, as the compact
+    # serialization permits: ``{}`` is ``e30``, an unsecured ``alg: none``
+    # token (RFC 7519 §6) has an empty signature, and detached content
+    # (RFC 7515 App. F) an empty payload. ``-`` is a token character here,
+    # so a ``-eyJ`` inside a segment is not a fresh candidate that rescans
+    # the run (base64url admits ``-``, and no escape starts inside one); each
+    # run is then scanned by at most three candidates and the pass stays
+    # linear. Placed before the shorter token shapes so one of them cannot
+    # replace a slice of the token and leave the rest unrecognised.
+    _token(
+        "jwt",
+        r"eyJ[A-Za-z0-9_-]{7,}\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*",
+        "***REDACTED***",
+        token_chars="A-Za-z0-9_-",
+    ),
+    # Google API keys (#282): ``AIza`` and 35 base64url characters, 39 in all,
+    # the key OpenCode launches inherit under ``GEMINI_*`` and ``GOOGLE_*``
+    # names, which no assignment pattern knows (#285); the shape recognises
+    # the value under any name, in a URL's ``?key=`` and alone. Case-sensitive
+    # and the whole token: ``-`` is a token character on both sides, as
+    # for a JWT, and a run of the key's characters that goes on past the 39
+    # is no key, so a near-miss of either length is left. The body is fixed,
+    # so each candidate scans at most 40 characters and the pass is linear.
+    # Placed before the GitHub and ``sk-`` shapes so that one starting after a
+    # ``-`` inside a key cannot replace a slice of it and leave the rest.
+    _token(
+        "google-api-key",
+        r"AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])",
+        "***REDACTED***",
+        token_chars="A-Za-z0-9_-",
+    ),
+    # GitHub fine-grained PATs
+    _token("github-fine-grained-pat", r"github_pat_[A-Za-z0-9_]{8,}", "***REDACTED***"),
+    # GitHub classic PATs and app / OAuth tokens
+    _token("github-token", r"gh[pousr]_[A-Za-z0-9_]{8,}", "***REDACTED***"),
+    # OpenAI-style sk- keys (incl. project variant sk-proj-...)
+    _token("openai-key", r"sk-(?:proj-)?[A-Za-z0-9_-]{8,}", "***REDACTED***"),
+    # Anthropic keys
+    _token("anthropic-key", r"sk-ant-[A-Za-z0-9_-]{8,}", "***REDACTED***"),
+    # Generic long bearer-ish assignments: token/password/secret = <value>.
+    # ``_`` is a token character before the name, so a prefixed one
+    # (``GEMINI_API_KEY=``) is not recognised here (#285); a Google API key
+    # under it is, by its shape (``google-api-key``).
+    _token(
+        "secret-assignment",
+        rf"(token|passwd|password|secret|api[_-]?key)(\s*[:=]\s*)({_QUOTE})"
+        rf"([A-Za-z0-9_\-./+]{{12,}})({_QUOTE})",
+        r"\1\2\3***REDACTED***\5",
+        flags="(?i)",
+    ),
+    # OAuth credential fields as a quoted key and value, the shape of an OAuth
+    # token response, Pi's ``auth.json`` and a Python mapping's repr:
+    # ``"refresh": "..."``, ``'access_token': '...'``, ``"id_token": "..."``,
+    # ``"chatgpt_account_id": "..."``. Only a quoted key followed by a quoted
+    # value matches, so prose ("refresh the page", "access: denied") is
+    # untouched. A quote starts it, so it needs no ``after_escape`` pass. The
+    # same escaping before both quotes (``\"refresh\": \"...``)
+    # covers JSON carried inside a JSON string; the bound on it keeps a run of
+    # backslashes from being rescanned from every position.
+    _Pattern(
+        "oauth-field",
+        re.compile(
+            rf"(?i)(\\{{0,7}})([\"'])({_OAUTH_FIELD_NAMES})\1\2(\s*:\s*\\{{0,7}}[\"'])[^\"'\s\\]+"
+        ),
+        r"\1\2\3\1\2\4***REDACTED***",
+    ),
+    # The same credentials as an assignment or header: ``refresh_token=...``
+    # (a query string, a form body, a shell variable), ``id_token: ...`` and
+    # the ``chatgpt-account-id: ...`` request header. ``_`` is no token
+    # character before the name, so a prefixed one (``oauth_refresh_token=``)
+    # is caught too.
+    _token(
+        "oauth-assignment",
+        r"((?:refresh|access|id)_token|chatgpt[-_]account[-_]id)"
+        rf"(\s*[:=]\s*)({_QUOTE})(?:[^\s\"';,&\\]|{_VALUE_BACKSLASH})+",
+        r"\1\2\3***REDACTED***",
+        flags="(?i)",
+        token_chars="A-Za-z0-9",
+    ),
+    # Bare ``refresh=`` / ``access=`` with a token-length value. Those words
+    # are ordinary prose, so only an ``=`` assignment of at least 16
+    # characters counts; ``access: denied`` and ``refresh=true`` stay.
+    _token(
+        "oauth-bare-assignment",
+        rf"(refresh|access)(=)({_QUOTE})(?:[^\s\"';,&\\]|{_VALUE_BACKSLASH}){{16,}}",
+        r"\1\2\3***REDACTED***",
+        flags="(?i)",
+    ),
+)
+
+_REDACTED = "***REDACTED***"
+
+# A mapping key that names an OAuth credential field, whole (``fullmatch``).
+# ``{"refresh": "..."}`` is the shape ``oauth-field`` finds in a text, but
+# :func:`redact_obj` hands :func:`redact` the key and its value apart, and
+# neither matches on its own; this is how it still sees the shape.
+_OAUTH_FIELD_KEY = re.compile(rf"(?i){_OAUTH_FIELD_NAMES}")
+
+# :func:`redact` never returns more than this many times its input's length.
+# Every pattern replaces a run of at least one character with the 14-character
+# marker, so a text can *grow* under redaction; the worst shape is a one
+# character credential in the shortest URL that carries one: ``ab://x@`` is 7
+# characters and becomes 20, a factor of 2.86, and it repeats without a
+# separator (``@`` ends a word), so a text of that shape and no other reaches
+# the ratio and no text exceeds it. The next worst is a one character secret
+# behind the shortest recognised name: ``HF_TOKEN=x``, 10 to 23 (``id_token=x``
+# is the same). Growth does not compound across patterns: a later pattern can
+# only lengthen the text by matching a run *shorter* than the marker, and a
+# marker is never part of such a run. The value classes that admit ``*`` (the
+# named-assignment, header, URL-userinfo and OAuth-field values) can only take
+# a marker in whole, since none of the characters that end such a run occurs
+# in the marker, so a match containing one is already at least as long as its
+# replacement and shrinks or keeps the length; every other value class excludes
+# ``*``, so a marker is never part of those matches at all. The characters
+# around a replaced run are untouched, so no new short match appears beside it.
+# An ``after_escape`` pass is one more pattern in that order, and the escape
+# sequence it starts at (#284) is put back unchanged, no part of the replaced
+# run; at two characters or more it separates repeated matches no tighter
+# than the one-character separators above, so it raises no ratio either.
+# The escaped quote an assignment's value may stand in (#281, ``_QUOTE``) is
+# kept like a plain one, no part of the replaced run either.
+# ``tests/test_redaction.py`` pins the factor against the worst-case shape of
+# every pattern and the wrapping case; a new pattern must keep it, or raise
+# it together with the persisted bound in :mod:`autoforge.loop_guard` that
+# depends on it.
+MAX_GROWTH_FACTOR = 3
+
+
+def redact(text: str | None) -> str:
+    """Redact known secret shapes. Never raises; non-str input -> str()."""
+    if text is None:
+        return ""
+    if not isinstance(text, str):
+        text = str(text)
+    for entry in _PATTERNS:
+        text = _apply(entry, text)
+    return text
+
+
+def _apply(entry: _Pattern, text: str) -> str:
+    """``text`` with one pattern's passes applied, ``after_escape`` second."""
+    text = entry.regex.sub(entry.replacement, text)
+    if entry.after_escape is not None:
+        text = entry.after_escape.sub(entry.escape_replacement, text)
+    return text
+
+
+def credential_classes(text: str) -> tuple[str, ...]:
+    """The class names of the patterns :func:`redact` would apply to ``text``.
+
+    Runs the same sequential substitution as :func:`redact` and records each
+    pattern that changed the text, in pattern order and each name once. The
+    result is empty exactly when ``redact(text) == text``: a text with a
+    credential shape is refused by name, never redacted and published.
+    """
+    found: list[str] = []
+    redacted = text
+    for entry in _PATTERNS:
+        replaced = _apply(entry, redacted)
+        if replaced != redacted:
+            found.append(entry.name)
+        redacted = replaced
+    # Exact by construction: should a later pattern ever restore what an
+    # earlier one changed, the text is still what ``redact`` returns.
+    return tuple(found) if redacted != text else ()
+
+
+def redact_argv(argv: list[str]) -> list[str]:
+    return [redact(a) for a in argv]
+
+
+def redact_obj(value: object) -> object:
+    """Recursively redact every string inside a JSON-shaped structure.
+
+    Log metadata and agent-supplied CONTROL_RESULT fields are persisted as
+    nested dicts/lists, so redacting only the top-level text would leave a
+    secret sitting one level down (``metadata["validation_command"]``, a
+    finding's ``required_resolution``). Mapping *keys* are redacted too: a key
+    is as capable of carrying a token as a value. Non-string scalars are
+    returned unchanged; anything exotic is stringified through `redact`, which
+    never raises.
+
+    Each string is redacted on its own, never as part of a serialized
+    document: a pattern run over JSON text can consume the syntax around a
+    value (an empty ``GITHUB_TOKEN=`` takes the closing quote, #206), so the
+    redacted text may no longer parse. (A secret right after an escape there,
+    ``\\n`` or ``\\u00e9``, follows a letter or a digit, and a quoted value
+    stands behind ``\\"``; they are recognised since #284 and #281, but the
+    syntax is still at risk.) The one shape that spans a key
+    and its value, a quoted OAuth credential field (``"refresh": "..."``,
+    ``oauth-field``), is recognised by the key instead: a non-empty string
+    under a key that names such a field, whole and in any case, is replaced
+    whole. No key of a
+    parser-bounded field (a finding, a resolution) names one, so the bounds
+    that depend on :data:`MAX_GROWTH_FACTOR` still hold.
+
+    A mapping never loses an entry to redaction. Two distinct keys can
+    redact to the same text (``GITHUB_TOKEN=a`` and ``GITHUB_TOKEN=b`` both
+    become ``GITHUB_TOKEN=***REDACTED***``), and a hand-edited journal or a
+    free-form ``escalation`` mapping can carry such keys; letting the later
+    entry overwrite the earlier one would drop a value from the diagnostic
+    output while the file on disk still holds it. A colliding key is instead
+    suffixed ``#2``, ``#3``, ... in insertion order, so every value is kept,
+    every key stays redacted, and the collision is visible in the output.
+    The next suffix is remembered per colliding text, so a mapping whose keys
+    all collide (an ``escalation`` mapping is free-form and the state file can
+    be tens of megabytes) is redacted in time linear in its size rather than
+    rescanning the taken suffixes from ``#2`` for every entry.
+    """
+    if isinstance(value, str):
+        return redact(value)
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, dict):
+        result: dict = {}
+        # Suffixes are handed out in increasing order per colliding text, so
+        # each taken suffix is stepped over at most once: an input key that
+        # already reads ``text#n`` is skipped, never rescanned.
+        next_suffix: dict[str, int] = {}
+        for k, v in value.items():
+            key = redact(str(k))
+            if key in result:
+                n = next_suffix.get(key, 2)
+                while f"{key}#{n}" in result:
+                    n += 1
+                next_suffix[key] = n + 1
+                key = f"{key}#{n}"
+            if isinstance(k, str) and isinstance(v, str) and v and _OAUTH_FIELD_KEY.fullmatch(k):
+                result[key] = _REDACTED
+            else:
+                result[key] = redact_obj(v)
+        return result
+    if isinstance(value, (list, tuple)):
+        return [redact_obj(v) for v in value]
+    return redact(str(value))
+
+
+def redact_dict(value: dict) -> dict:
+    """`redact_obj` for a mapping, typed for callers that persist dicts."""
+    result = redact_obj(value)
+    return result if isinstance(result, dict) else {}

autoforge/replan.py

@@ -0,0 +1,208 @@
+"""Deterministic REPLAN_REEXECUTE policy and compact history collection."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .config import ReplanConfig
+from .github import GitHubClient
+from .loop_guard import RESULT_NEEDS_FIX, truncated_evidence_rounds
+
+# Any run of three or more tildes can close (or open) a tilde code fence, so
+# the escape must break *runs*, not the literal fence string: replacing only
+# "~~~~" is non-overlapping and left-to-right, which lets "~~~~~~~" re-form a
+# closing fence out of the untouched tail.
+_TILDE_RUN_RE = re.compile(r"~{3,}")
+
+
+@dataclass(frozen=True)
+class ReplanDecision:
+    action: str  # continue_fix | replan | block_for_human
+    reason: str = ""
+    metadata: dict[str, object] | None = None
+
+
+def evaluate_replan_policy(
+    *,
+    has_actionable_findings: bool,
+    current_review_round: int,
+    review_history: list[dict],
+    escalation_count: int,
+    config: ReplanConfig,
+    workflow_stagnation_reason: str = "",
+) -> ReplanDecision:
+    """Choose the post-review route without inspecting agent prose.
+
+    A clean review always wins. ``max_replans_per_issue`` counts completed
+    fresh reimplementations, not the original implementation attempt.
+
+    A replan is refused outright while any recorded round's findings are
+    truncated (:func:`~autoforge.loop_guard.truncated_evidence_rounds`): that
+    evidence is what the replacement must answer for, and the old PR is the
+    only remaining copy of it.
+
+    ``soft_threshold`` is the review round from which the controller may
+    *replace* an implementation instead of continuing to patch it. Every
+    stagnation trigger is gated behind it, including the ``workflow.stagnation_*``
+    verdict passed in as ``workflow_stagnation_reason``: an early streak of
+    identical resolutions is usually a single FIX round that missed a finding,
+    and discarding the whole PR over that is far more destructive than the
+    documented BLOCKED. Below the threshold this returns ``continue_fix`` and
+    the caller's ordinary loop bounds (cap / stagnation -> BLOCKED) apply
+    unchanged; at or above it, sustained non-convergence escalates to a replan.
+
+    The window rule (``stagnation_window`` trailing rounds with findings, each
+    holding at most ``max_findings_per_round`` of them) deliberately counts
+    rounds of *entirely new* findings. Unlike ``workflow.stagnation_*`` it
+    requires no recurring ``required_resolution``: recurrence is what those
+    rules already detect, and their verdict arrives here as
+    ``workflow_stagnation_reason``, so a recurrence requirement would leave
+    this rule nothing of its own to catch. Its purpose is the long tail -- an
+    implementation that, ``soft_threshold`` rounds in, still draws a small
+    but never-ending trickle of fresh findings from every review. Below the
+    threshold such rounds are progress bounded by the round cap only, exactly
+    as the workflow rules treat them; the threshold, not a recurrence, is
+    what protects a productive loop from being replaced.
+    """
+    if not has_actionable_findings or not config.enabled:
+        return ReplanDecision("continue_fix")
+
+    trigger = ""
+    metadata: dict[str, object] = {
+        "current_round": current_review_round,
+        "soft_threshold": config.soft_threshold,
+        "hard_threshold": config.hard_threshold,
+    }
+    if workflow_stagnation_reason and current_review_round >= config.soft_threshold:
+        trigger = "workflow_stagnation"
+        metadata["workflow_stagnation_reason"] = workflow_stagnation_reason
+    elif current_review_round >= config.hard_threshold:
+        trigger = "hard_review_round_threshold"
+    elif current_review_round >= config.soft_threshold:
+        window = config.stagnation_window
+        tail = review_history[-window:]
+        counts = [r.get("finding_count") for r in tail]
+        metadata.update(
+            {
+                "stagnation_window": window,
+                "max_findings_per_round": config.max_findings_per_round,
+                "recent_finding_counts": counts,
+            }
+        )
+        if (
+            len(tail) == window
+            and all(r.get("result") == RESULT_NEEDS_FIX for r in tail)
+            and all(
+                isinstance(count, int) and count <= config.max_findings_per_round
+                for count in counts
+            )
+        ):
+            trigger = "stagnation_after_soft_threshold"
+    if not trigger:
+        return ReplanDecision("continue_fix")
+    metadata["trigger"] = trigger
+    metadata["replan_count"] = escalation_count
+    metadata["max_replans_per_issue"] = config.max_replans_per_issue
+    truncated = truncated_evidence_rounds(review_history)
+    if truncated:
+        # Superseding the PR deletes the controller's record of its findings.
+        # If that record is already incomplete, the replacement protocol cannot
+        # require the agent to consider the missing findings, and closing the
+        # PR would drop them for good. Keep the PR and the findings for a human.
+        metadata["truncated_evidence_rounds"] = truncated
+        return ReplanDecision("block_for_human", "replan_evidence_truncated", metadata)
+    if escalation_count >= config.max_replans_per_issue:
+        return ReplanDecision("block_for_human", "replan_limit_exceeded", metadata)
+    return ReplanDecision("replan", trigger, metadata)
+
+
+@dataclass(frozen=True)
+class HistoricalReviewData:
+    findings: list[dict]
+    observations: list[str]
+    verification_failures: list[str]
+    # Number of findings actually rendered into the prompt, which the agent
+    # must account for exactly. A replan only gets this far when no round was
+    # truncated (``evaluate_replan_policy`` and ``_prepare_replan`` both refuse
+    # otherwise), so this equals the reviews' own untruncated finding counts.
+    recorded_finding_count: int = 0
+
+    @staticmethod
+    def _render_untrusted(text: str) -> str:
+        """Prevent collected text from terminating the prompt's outer fence.
+
+        Every run of 3+ tildes is broken apart, so no residual run of any
+        length (indented or not) can act as a fence delimiter.
+        """
+        return _TILDE_RUN_RE.sub(lambda m: " ".join(m.group(0)), text)
+
+    def render_findings(self) -> str:
+        if not self.findings:
+            return "(none)"
+        return self._render_untrusted(
+            "\n".join(
+                "- {id} (round {round}, {classification}): {required_resolution}".format(
+                    id=f.get("id", "(unknown)"),
+                    round=f.get("round", "?"),
+                    classification=f.get("classification", "unknown"),
+                    required_resolution=f.get("required_resolution", ""),
+                )
+                for f in self.findings
+            )
+        )
+
+    def render_observations(self) -> str:
+        if not self.observations:
+            return "(none)"
+        return self._render_untrusted("\n\n".join(self.observations))
+
+    def render_verification_failures(self) -> str:
+        if not self.verification_failures:
+            return "(none)"
+        return self._render_untrusted("\n".join(self.verification_failures))
+
+
+class HistoricalReviewCollector:
+    """Collect bounded, typed review evidence before an implementation is abandoned.
+
+    State carries compact finding summaries and GitHub remains the source for
+    review-comment bodies. Only comments referenced by the persisted review
+    rounds are collected; arbitrary PR conversation is never injected.
+    """
+
+    def __init__(self, github: GitHubClient, max_comment_chars: int = 24000) -> None:
+        self.github = github
+        self.max_comment_chars = max_comment_chars
+
+    def collect(
+        self,
+        previous_pr_url: str,
+        review_history: list[dict],
+        verification_failures: list[str],
+    ) -> HistoricalReviewData:
+        findings: list[dict] = []
+        observations: list[str] = []
+        comments = {c.url: c for c in self.github.get_pr_comments(previous_pr_url)}
+        remaining = self.max_comment_chars
+        for record in review_history:
+            if record.get("result") != RESULT_NEEDS_FIX:
+                continue
+            round_number = record.get("round")
+            for finding in record.get("findings", []):
+                if isinstance(finding, dict):
+                    findings.append({"round": round_number, **finding})
+            comment_url = record.get("review_comment_url", "")
+            comment = comments.get(comment_url)
+            if comment is not None and comment.body and remaining > 0:
+                body = comment.body[:remaining]
+                observations.append(
+                    f"Review round {round_number} comment ({comment.url}, untrusted data):\n{body}"
+                )
+                remaining -= len(body)
+        return HistoricalReviewData(
+            findings,
+            observations,
+            list(verification_failures),
+            len(findings),
+        )