code-mower 0.5.0b45__tar.gz → 0.5.0b47__tar.gz

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.5.0b45
+Version: 0.5.0b47
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
@@ -103,11 +103,11 @@ Code Mower currently targets Python 3.11+; Python 3.12 is recommended.
 
 ```bash
 python3.12 --version
-pipx install --python python3.12 code-mower==0.5.0b45
+pipx install --python python3.12 code-mower==0.5.0b47
 code-mower --version
 ```
 
-`0.5.0b45` is a beta release. Until Code Mower publishes a stable `1.0`
+`0.5.0b47` is a beta release. Until Code Mower publishes a stable `1.0`
 line, use the explicit beta version above or allow prereleases with:
 
 ```bash
@@ -155,7 +155,7 @@ First-time command map: [docs/launch-command-surface.md](docs/launch-command-sur
 
 The current PyPI beta has been rehearsed end-to-end from a clean install:
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the latest 10/10 public-package readiness proof for `code-mower==0.5.0b45`.
+the latest 10/10 public-package readiness proof for `code-mower==0.5.0b47`.
 
 ## Optional: Plan Before Coding
 
@@ -310,9 +310,9 @@ builder provenance, start with
 
 ## Installation Status
 
-The current public beta is `v0.5.0-beta.45` from
+The current public beta is `v0.5.0-beta.47` from
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), published
-as `code-mower==0.5.0b45` on [PyPI](https://pypi.org/project/code-mower/).
+as `code-mower==0.5.0b47` on [PyPI](https://pypi.org/project/code-mower/).
 GitHub releases remain the auditable source for tags, build artifacts, and
 release notes.
 

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/README.md

@@ -88,11 +88,11 @@ Code Mower currently targets Python 3.11+; Python 3.12 is recommended.
 
 ```bash
 python3.12 --version
-pipx install --python python3.12 code-mower==0.5.0b45
+pipx install --python python3.12 code-mower==0.5.0b47
 code-mower --version
 ```
 
-`0.5.0b45` is a beta release. Until Code Mower publishes a stable `1.0`
+`0.5.0b47` is a beta release. Until Code Mower publishes a stable `1.0`
 line, use the explicit beta version above or allow prereleases with:
 
 ```bash
@@ -140,7 +140,7 @@ First-time command map: [docs/launch-command-surface.md](docs/launch-command-sur
 
 The current PyPI beta has been rehearsed end-to-end from a clean install:
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the latest 10/10 public-package readiness proof for `code-mower==0.5.0b45`.
+the latest 10/10 public-package readiness proof for `code-mower==0.5.0b47`.
 
 ## Optional: Plan Before Coding
 
@@ -295,9 +295,9 @@ builder provenance, start with
 
 ## Installation Status
 
-The current public beta is `v0.5.0-beta.45` from
+The current public beta is `v0.5.0-beta.47` from
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), published
-as `code-mower==0.5.0b45` on [PyPI](https://pypi.org/project/code-mower/).
+as `code-mower==0.5.0b47` on [PyPI](https://pypi.org/project/code-mower/).
 GitHub releases remain the auditable source for tags, build artifacts, and
 release notes.
 

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-mower"
-version = "0.5.0b45"
+version = "0.5.0b47"
 description = "Multi-reviewer AI code audit orchestration"
 requires-python = ">=3.11"
 readme = "README.md"

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/__init__.py

@@ -1,3 +1,3 @@
 """Code Mower package."""
 
-__version__ = "0.5.0b45"
+__version__ = "0.5.0b47"

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/audit_labeler_lib.py

@@ -10,6 +10,7 @@ has proven the shared library on main.
 from __future__ import annotations
 
 import functools
+import hashlib
 import json
 import os
 import sys
@@ -24,7 +25,9 @@ import re
 MIN_ABBREVIATED_SHA_LENGTH = 7
 AUTHOR_EXCLUSION_ENV = "CODE_MOWER_AUTHOR_EXCLUSION_JSON"
 ACTIONS_RUN_MARKER_RE = re.compile(
-    r"<!--\s*CODE_MOWER_AUDIT_RUN:\s*run_id=([0-9]+)\s*-->"
+    r"<!--\s*CODE_MOWER_AUDIT_RUN:\s*run_id=([0-9]+)"
+    r"(?:\s+comment_id=([0-9]+))?"
+    r"(?:\s+body_sha256=([0-9a-f]{64}))?\s*-->"
 )
 TRUSTED_ACTIONS_AUDIT_EVENTS = frozenset({"pull_request_target"})
 
@@ -44,6 +47,13 @@ class GitHubToken:
     value: str
 
 
+@dataclass(frozen=True)
+class ActionsRunMarker:
+    run_id: str
+    comment_id: str
+    body_sha256: str
+
+
 @dataclass(frozen=True)
 class LaneConfig:
     name: str
@@ -300,8 +310,32 @@ def parse_csv_set(raw: str) -> frozenset[str]:
 
 
 def parse_audit_run_id(body: str) -> str:
+    marker = parse_audit_run_marker(body)
+    return marker.run_id if marker else ""
+
+
+def parse_audit_run_marker(body: str) -> Optional[ActionsRunMarker]:
+    match = ACTIONS_RUN_MARKER_RE.search(body)
+    if not match:
+        return None
+    return ActionsRunMarker(
+        run_id=match.group(1),
+        comment_id=match.group(2) or "",
+        body_sha256=match.group(3) or "",
+    )
+
+
+def audit_run_marker_body_digest_matches(body: str) -> bool:
     match = ACTIONS_RUN_MARKER_RE.search(body)
-    return match.group(1) if match else ""
+    if not match or not match.group(2) or not match.group(3):
+        return False
+    canonical_marker = (
+        "<!-- CODE_MOWER_AUDIT_RUN: "
+        f"run_id={match.group(1)} comment_id={match.group(2)} -->"
+    )
+    canonical_body = body[: match.start()] + canonical_marker + body[match.end() :]
+    digest = hashlib.sha256(canonical_body.encode("utf-8")).hexdigest()
+    return digest == match.group(3)
 
 
 def workflow_path_matches(path: str, trusted_workflows: Sequence[str]) -> bool:
@@ -357,6 +391,7 @@ def github_actions_comment_attested(
     *,
     repo: str,
     body: str,
+    comment_id: int | str | None = None,
     issue_number: int,
     head_sha: str,
     workflow_paths: Sequence[str],
@@ -367,14 +402,19 @@ def github_actions_comment_attested(
     """Return whether a github-actions[bot] audit comment is tied to this PR head."""
     trusted_workflows = tuple(parse_csv_set(",".join(workflow_paths)))
     token_list = tuple(token for token in tokens if token.value)
-    run_id = parse_audit_run_id(body)
-    if not trusted_workflows or not token_list or not run_id or not head_sha:
+    marker = parse_audit_run_marker(body)
+    comment_id_text = str(comment_id or "").strip()
+    if not trusted_workflows or not token_list or marker is None or not head_sha:
+        return False
+    if not comment_id_text or marker.comment_id != comment_id_text:
+        return False
+    if not audit_run_marker_body_digest_matches(body):
         return False
     try:
         if actions_run_lookup is None:
-            run = fetch_actions_run(repo, run_id, tokens=token_list)
+            run = fetch_actions_run(repo, marker.run_id, tokens=token_list)
         else:
-            run = dict(actions_run_lookup(run_id))
+            run = dict(actions_run_lookup(marker.run_id))
     except Exception:
         return False
 

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/claude_audit_pr.py

@@ -21,6 +21,7 @@ import tempfile
 import time
 import urllib.error
 from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -33,7 +34,9 @@ if __package__ in {None, "", "tools"}:
         from tools.claude_cli_environment import clean_claude_cli_env, env_flag
         from tools.provider_runners import (
             audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+            bind_actions_run_comment_id,
             clip_text as _clip_text,
+            edit_pr_comment,
             fetch_pull_request,
             fetch_base_ref_sha as _shared_fetch_base_ref_sha,
             fetch_pr_head_sha as _shared_fetch_pr_head_sha,
@@ -61,7 +64,9 @@ if __package__ in {None, "", "tools"}:
         from claude_cli_environment import clean_claude_cli_env, env_flag  # type: ignore
         from provider_runners import (  # type: ignore
             audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+            bind_actions_run_comment_id,
             clip_text as _clip_text,
+            edit_pr_comment,
             fetch_pull_request,
             fetch_base_ref_sha as _shared_fetch_base_ref_sha,
             fetch_pr_head_sha as _shared_fetch_pr_head_sha,
@@ -87,7 +92,9 @@ else:  # pragma: no cover - exercised after package extraction.
     from .provider_runners import (
         FetchedHeadMismatch,
         audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+        bind_actions_run_comment_id,
         clip_text as _clip_text,
+        edit_pr_comment,
         fetch_base_ref_sha as _shared_fetch_base_ref_sha,
         fetch_pull_request,
         fetch_pr_head_sha as _shared_fetch_pr_head_sha,
@@ -123,11 +130,32 @@ MIN_BLOCKED_VERDICT_PROSE_CHARS = 80
 SCHEMA_PLACEHOLDER_TEXT = frozenset({"test", "example", "placeholder"})
 CLAUDE_RAW_OUTPUT_SCHEMA = "code_mower.claudeAuditRawOutput.v1"
 BLOCKER_SEVERITIES = frozenset({"P0", "P1", "P2"})
+DEFAULT_CLAUDE_CLI_FAILURE_DIR = (
+    Path.home() / ".cache" / "code-mower-audits" / "cli-failures"
+)
 
 STALE_TRAILER = "<!-- CLAUDE_AUDIT_STATE: needs-claude-audit -->"
 DONE_TRAILER = "<!-- CLAUDE_AUDIT_STATE: claude-audit-done -->"
 BLOCKED_TRAILER = "<!-- CLAUDE_AUDIT_STATE: claude-audit-blocked -->"
 AUDIT_RUN_TRAILER_PREFIX = "<!-- CODE_MOWER_AUDIT_RUN:"
+STALE_REQUEUE_MARKER = "<!-- CODE_MOWER_AUDIT_REQUEUE: kind=stale -->"
+UNKNOWN_REQUEUE_MARKER = "<!-- CODE_MOWER_AUDIT_REQUEUE: kind=unknown -->"
+
+
+def _post_audit_comment(
+    repo: str,
+    pr_number: int,
+    body: str,
+    *,
+    token: str,
+    actions_run_id: Optional[str],
+) -> tuple[dict[str, Any], str]:
+    posted = post_pr_comment(repo, pr_number, body, token=token)
+    if not actions_run_id:
+        return posted, body
+    bound_body = bind_actions_run_comment_id(body, posted.get("id"))
+    edited = edit_pr_comment(repo, posted["id"], bound_body, token=token)
+    return edited if isinstance(edited, dict) else posted, bound_body
 
 
 CLAUDE_VERDICT_SCHEMA: Dict[str, Any] = {
@@ -492,6 +520,104 @@ def _write_claude_raw_output_sidecar(
         )
 
 
+def _claude_status_payload(stdout: str, stderr: str) -> Dict[str, Any]:
+    candidates = [stdout.strip(), stderr.strip()]
+    candidates.extend(
+        line.strip()
+        for text in (stdout, stderr)
+        for line in reversed(text.splitlines())
+    )
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            payload = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(payload, dict):
+            return payload
+    return {}
+
+
+def _claude_payload_text(payload: Dict[str, Any], key: str, limit: int = 500) -> str:
+    value = payload.get(key)
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        text = json.dumps(value, sort_keys=True)
+    else:
+        text = str(value)
+    return _one_line(text, limit)
+
+
+def _claude_cli_failure_reason(stdout: str, stderr: str) -> str:
+    payload = _claude_status_payload(stdout, stderr)
+    if not payload:
+        return ""
+    result = _claude_payload_text(payload, "result", 160)
+    terminal_reason = _claude_payload_text(payload, "terminal_reason", 160)
+    status = _claude_payload_text(payload, "api_error_status", 40)
+    reason = result.split(" · ", 1)[0].strip() or terminal_reason
+    if not reason and status:
+        reason = f"API error {status}"
+    return f"Claude CLI: {reason}" if reason else ""
+
+
+def _dump_claude_cli_failure(
+    *,
+    repo: str,
+    pr_number: int,
+    head_sha: str,
+    stdout: str,
+    stderr: str,
+    reason: str,
+    base_dir: Optional[Path] = None,
+) -> Optional[Path]:
+    try:
+        base_dir = base_dir or DEFAULT_CLAUDE_CLI_FAILURE_DIR
+        base_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        try:
+            os.chmod(base_dir, 0o700)
+        except OSError:
+            pass
+        owner_name = repo.replace("/", "_")
+        short_sha = (head_sha or "unknown")[:12]
+        ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S_%fZ")
+        path = base_dir / f"{owner_name}_pr{pr_number}_{short_sha}_{ts}_claude.log"
+        payload = _claude_status_payload(stdout, stderr)
+        field_lines = ""
+        for key in ("result", "terminal_reason", "api_error_status"):
+            value = _claude_payload_text(payload, key)
+            if value:
+                field_lines += f"# claude_{key}: {value}\n"
+        body = (
+            "# Claude CLI raw output - structured verdict was unusable\n"
+            f"# repo: {repo}\n"
+            f"# pr: {pr_number}\n"
+            f"# head_sha: {head_sha}\n"
+            f"# captured_at: {ts}\n"
+            f"# diagnostic_reason: {reason}\n"
+            f"{field_lines}"
+            f"# stdout_bytes: {len(stdout.encode('utf-8'))}\n"
+            f"# stderr_bytes: {len(stderr.encode('utf-8'))}\n"
+            "\n===== STDOUT =====\n"
+            + (stdout if stdout else "<empty>\n")
+            + "\n===== STDERR =====\n"
+            + (stderr if stderr else "<empty>\n")
+        )
+        fd = os.open(
+            str(path),
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
+            0o600,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(body)
+        return path
+    except OSError as exc:
+        print(f"  warning: failed to dump Claude CLI output: {exc}", file=sys.stderr)
+        return None
+
+
 def _guardrail_retry_prompt(
     prompt: str,
     reason: str,
@@ -899,6 +1025,7 @@ def format_comment(
     is_unknown: bool = False,
     merge_authority: bool = True,
     actions_run_id: Optional[str] = None,
+    unknown_reason: str = "",
 ) -> str:
     posture = "merge-authority lane" if merge_authority else "informational only"
     header = f"## Claude audit ({posture})\n\n"
@@ -911,16 +1038,23 @@ def format_comment(
             + f"\nHead SHA changed during review (`{head_sha[:8]}` -> "
             + f"`{(stale_end_sha or '?')[:8]}`). Skipping this verdict and "
             + "requeuing for re-review of the new head.\n\n"
+            + STALE_REQUEUE_MARKER
+            + "\n"
             + STALE_TRAILER
             + "\n"
         )
         return limit_comment_body(body, STALE_TRAILER, provider_name="Claude")
     if is_unknown:
+        reason_line = f"\n\n{unknown_reason}." if unknown_reason else ""
         body = (
             header
             + "\nCould not validate a Claude structured verdict artifact. "
             + "The CLI may have failed, exceeded budget, or emitted no "
-            + "schema-valid structured output. Requeuing for re-review.\n\n"
+            + "schema-valid structured output. Requeuing for re-review."
+            + reason_line
+            + "\n\n"
+            + UNKNOWN_REQUEUE_MARKER
+            + "\n"
             + STALE_TRAILER
             + "\n"
         )
@@ -996,6 +1130,7 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
             config.max_diff_hard_limit_bytes,
         )
     except FetchedHeadMismatch as exc:
+        actions_run_id = os.environ.get("GITHUB_RUN_ID") or None
         print(
             f"  force-push race: fetched head {exc.actual_sha[:8]} does not "
             f"match recorded head {exc.expected_sha[:8]}; emitting STALE",
@@ -1012,6 +1147,7 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
             is_stale=True,
             stale_end_sha=exc.actual_sha,
             merge_authority=config.merge_authority,
+            actions_run_id=actions_run_id,
         )
         result = ClaudeAuditResult(
             repo=repo,
@@ -1066,7 +1202,14 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
                         quarantine_reason,
                     )
                     result.comment_body = comment_body
-                posted = post_pr_comment(repo, pr_number, comment_body, token=config.github_token)
+                posted, comment_body = _post_audit_comment(
+                    repo,
+                    pr_number,
+                    comment_body,
+                    token=config.github_token,
+                    actions_run_id=actions_run_id,
+                )
+                result.comment_body = comment_body
                 result.posted_comment_url = posted.get("html_url")
                 _record_posted_comment_url(
                     result.verdict_artifact_path,
@@ -1181,6 +1324,7 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
     head_sha_end = pr_meta_after["head"]["sha"]
     is_stale = head_sha_start != head_sha_end
     actions_run_id = os.environ.get("GITHUB_RUN_ID") or None
+    claude_cli_reason = _claude_cli_failure_reason(claude_stdout, claude_stderr)
 
     if is_stale:
         comment_body = format_comment(
@@ -1200,6 +1344,7 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
             is_unknown=True,
             merge_authority=config.merge_authority,
             actions_run_id=actions_run_id,
+            unknown_reason=claude_cli_reason,
         )
         result_verdict = "UNKNOWN"
         trailer = STALE_TRAILER
@@ -1227,6 +1372,21 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
     )
 
     if not config.dry_run:
+        if result_verdict == "UNKNOWN":
+            dump_path = _dump_claude_cli_failure(
+                repo=repo,
+                pr_number=pr_number,
+                head_sha=head_sha_start,
+                stdout=claude_stdout,
+                stderr=claude_stderr,
+                reason=parsed.prose,
+            )
+            if dump_path is not None:
+                print(
+                    f"  captured Claude CLI output for diagnosis: {dump_path}",
+                    file=sys.stderr,
+                    flush=True,
+                )
         quarantine_reason = _audit_runtime_quarantine_reason(
             comment_body=comment_body,
             fixture_reason=final_fixture_reason if parsed.verdict == "UNKNOWN" else None,
@@ -1269,7 +1429,14 @@ def audit_pr(config: ClaudeAuditConfig, repo: str, pr_number: int) -> ClaudeAudi
                     quarantine_reason,
                 )
                 result.comment_body = comment_body
-            posted = post_pr_comment(repo, pr_number, comment_body, token=config.github_token)
+            posted, comment_body = _post_audit_comment(
+                repo,
+                pr_number,
+                comment_body,
+                token=config.github_token,
+                actions_run_id=actions_run_id,
+            )
+            result.comment_body = comment_body
             result.posted_comment_url = posted.get("html_url")
             _record_posted_comment_url(
                 result.verdict_artifact_path,
@@ -1534,7 +1701,11 @@ def main(argv: Optional[List[str]] = None) -> int:
             print(f"spend metadata appended to {args.spend_path}", file=sys.stderr)
         except (OSError, ValueError) as exc:
             print(f"warning: failed to append spend metadata: {exc}", file=sys.stderr)
-    return 2 if result.verdict in {"STALE", "UNKNOWN"} else 0
+    return _audit_exit_code(result.verdict)
+
+
+def _audit_exit_code(verdict: str) -> int:
+    return 2 if verdict == "UNKNOWN" else 0
 
 
 if __name__ == "__main__":

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/cli.py

@@ -14,7 +14,7 @@ from pathlib import Path
 if __package__ in {None, ""}:
     raise SystemExit(
         "code_mower.cli is a packaged entrypoint. Install Code Mower with "
-        "`pipx install code-mower==0.5.0b45`, or run source checkouts with "
+        "`pipx install code-mower==0.5.0b47`, or run source checkouts with "
         "`PYTHONPATH=src python -m code_mower.cli`."
     )
 

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/code_mower_telemetry.py

@@ -229,6 +229,8 @@ def reviewer_run_event_from_verdict_artifact(
     duration_seconds = _artifact_duration_seconds(payload)
     if duration_seconds is not None:
         metrics["duration_seconds_total"] = duration_seconds
+        metrics["duration_seconds"] = duration_seconds
+        metrics["wall_seconds"] = duration_seconds
         dimensions["duration_source"] = "verdict_artifact"
     return {
         "schema": BENCHMARK_EVENT_SCHEMA,

{code_mower-0.5.0b45 → code_mower-0.5.0b47}/src/code_mower/codex_audit_pr.py

@@ -57,7 +57,7 @@ daemon analogous to local_llm_audit_bridge.py):
 Exit codes (CLI mode):
     0  comment posted (or dry-run printed)
     1  generic error (config, network, Codex CLI failure)
-    2  stale head SHA detected mid-review (caller may requeue)
+    2  UNKNOWN verdict emitted (caller should requeue and investigate)
 
 Trailer protocol (mirrors Devin/local LLM):
     <!-- CODEX_AUDIT_STATE: codex-audit-done -->     (verdict was PASS)
@@ -90,7 +90,9 @@ if __package__ in {None, "", "tools"}:
         from tools.audit_progress import AuditProgress, run_subprocess_with_progress
         from tools.provider_runners import (
             audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+            bind_actions_run_comment_id,
             clip_text as _clip_text,
+            edit_pr_comment,
             fetch_pull_request,
             fetch_base_ref as _shared_fetch_base_ref,
             fetch_pr_head as _shared_fetch_pr_head,
@@ -115,7 +117,9 @@ if __package__ in {None, "", "tools"}:
         from audit_progress import AuditProgress, run_subprocess_with_progress  # type: ignore
         from provider_runners import (  # type: ignore
             audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+            bind_actions_run_comment_id,
             clip_text as _clip_text,
+            edit_pr_comment,
             fetch_pull_request,
             fetch_base_ref as _shared_fetch_base_ref,
             fetch_pr_head as _shared_fetch_pr_head,
@@ -140,8 +144,10 @@ else:  # pragma: no cover - exercised after package extraction.
     from .audit_progress import AuditProgress, run_subprocess_with_progress
     from .provider_runners import (
         audit_runtime_quarantine_reason as _audit_runtime_quarantine_reason,
+        bind_actions_run_comment_id,
         clip_text as _clip_text,
         create_temp_worktree as _shared_create_temp_worktree,
+        edit_pr_comment,
         fetch_base_ref as _shared_fetch_base_ref,
         fetch_pull_request,
         fetch_pr_head as _shared_fetch_pr_head,
@@ -319,6 +325,24 @@ STALE_TRAILER = "<!-- CODEX_AUDIT_STATE: needs-codex-audit -->"
 DONE_TRAILER = "<!-- CODEX_AUDIT_STATE: codex-audit-done -->"
 BLOCKED_TRAILER = "<!-- CODEX_AUDIT_STATE: codex-audit-blocked -->"
 AUDIT_RUN_TRAILER_PREFIX = "<!-- CODE_MOWER_AUDIT_RUN:"
+STALE_REQUEUE_MARKER = "<!-- CODE_MOWER_AUDIT_REQUEUE: kind=stale -->"
+UNKNOWN_REQUEUE_MARKER = "<!-- CODE_MOWER_AUDIT_REQUEUE: kind=unknown -->"
+
+
+def _post_audit_comment(
+    repo: str,
+    pr_number: int,
+    body: str,
+    *,
+    token: str,
+    actions_run_id: Optional[str],
+) -> tuple[dict[str, Any], str]:
+    posted = post_pr_comment(repo, pr_number, body, token=token)
+    if not actions_run_id:
+        return posted, body
+    bound_body = bind_actions_run_comment_id(body, posted.get("id"))
+    edited = edit_pr_comment(repo, posted["id"], bound_body, token=token)
+    return edited if isinstance(edited, dict) else posted, bound_body
 
 
 def _quarantine_is_test_only(reason: Optional[str]) -> bool:
@@ -1242,6 +1266,8 @@ def format_comment(
             + f"\nHead SHA changed during review (`{head_sha[:8]}` → "
             + f"`{(stale_end_sha or '?')[:8]}`). Skipping this verdict and "
             + "requeuing for re-review of the new head.\n\n"
+            + STALE_REQUEUE_MARKER
+            + "\n"
             + STALE_TRAILER
             + "\n"
         )
@@ -1254,6 +1280,8 @@ def format_comment(
             + "the structured-output pass may have failed, or the verdict "
             + "format may have drifted. "
             + "Requeuing for re-review.\n\n"
+            + UNKNOWN_REQUEUE_MARKER
+            + "\n"
             + STALE_TRAILER
             + "\n"
         )
@@ -1389,6 +1417,7 @@ def audit_pr(config: AuditConfig, repo: str, pr_number: int) -> AuditResult:
         pr_meta_after = fetch_pull_request(repo, pr_number, token=config.github_token)
         head_sha_after = pr_meta_after["head"]["sha"]
         if head_sha_after != head_sha_start:
+            actions_run_id = os.environ.get("GITHUB_RUN_ID") or None
             print(f"  force-push race: head moved from {head_sha_start[:8]} "
                   f"to {head_sha_after[:8]} during fetch; emitting STALE",
                   file=sys.stderr, flush=True)
@@ -1399,6 +1428,7 @@ def audit_pr(config: AuditConfig, repo: str, pr_number: int) -> AuditResult:
                 is_stale=True,
                 stale_end_sha=head_sha_after,
                 merge_authority=config.merge_authority,
+                actions_run_id=actions_run_id,
             )
             result = AuditResult(
                 repo=repo, pr_number=pr_number,
@@ -1458,8 +1488,14 @@ def audit_pr(config: AuditConfig, repo: str, pr_number: int) -> AuditResult:
                             quarantine_reason,
                         )
                         result.comment_body = comment_body
-                    posted = post_pr_comment(repo, pr_number, comment_body,
-                                              token=config.github_token)
+                    posted, comment_body = _post_audit_comment(
+                        repo,
+                        pr_number,
+                        comment_body,
+                        token=config.github_token,
+                        actions_run_id=actions_run_id,
+                    )
+                    result.comment_body = comment_body
                     result.posted_comment_url = posted.get("html_url")
             config.progress.emit(
                 "audit",
@@ -1657,8 +1693,14 @@ def audit_pr(config: AuditConfig, repo: str, pr_number: int) -> AuditResult:
                     quarantine_reason,
                 )
                 result.comment_body = comment_body
-            posted = post_pr_comment(repo, pr_number, comment_body,
-                                      token=config.github_token)
+            posted, comment_body = _post_audit_comment(
+                repo,
+                pr_number,
+                comment_body,
+                token=config.github_token,
+                actions_run_id=actions_run_id,
+            )
+            result.comment_body = comment_body
             result.posted_comment_url = posted.get("html_url")
             print(f"posted {repo}#{pr_number} verdict={result_verdict} "
                   f"url={result.posted_comment_url}", file=sys.stderr)
@@ -2016,14 +2058,15 @@ def main(argv: Optional[List[str]] = None) -> int:
         except (OSError, ValueError) as exc:
             print(f"warning: failed to append spend metadata: {exc}", file=sys.stderr)
 
-    # Codex round 7 of #234 — P2: both STALE and UNKNOWN result in a
-    # `needs-codex-audit` requeue comment. Automation using the exit
-    # code to decide whether to retry must see exit 2 for BOTH cases;
-    # otherwise UNKNOWN looks like a successful audit even though the
-    # comment requests re-review.
-    if result.verdict in ("STALE", "UNKNOWN"):
-        return 2
-    return 0
+    return _audit_exit_code(result.verdict)
+
+
+def _audit_exit_code(verdict: str) -> int:
+    # UNKNOWN still means the lane produced no trustworthy verdict and should
+    # fail loudly. STALE means a newer head superseded this run after the wrapper
+    # posted a requeue note, so returning success avoids alarm-grade noise while
+    # the newer head's audit becomes authoritative.
+    return 2 if verdict == "UNKNOWN" else 0
 
 
 if __name__ == "__main__":