claude-dev-env 2.16.0 → 2.18.0

package/_shared/pr-loop/scripts/check_convergence_thread_gates.py

@@ -0,0 +1,219 @@
+"""Review-thread and pending-reviewer IO leaves for the convergence gate checks.
+
+Each function issues one ``gh`` call (GraphQL or REST) and returns a
+``(passed, detail)`` pair the convergence checker turns into a PASS/FAIL line.
+The checker re-imports these names, so a test patches them on the checker module.
+"""
+
+from __future__ import annotations
+
+import json
+
+import _pr_converge_path_setup  # noqa: F401
+from check_convergence_gates import (
+    JsonObject,
+    ReviewStateGroup,
+    _gh_api,
+    _run_gh_command,
+)
+from pr_converge_skill_constants.constants import (
+    CLAUDE_LOGIN_FILTER_SUBSTRING,
+    COPILOT_LOGIN_FILTER_SUBSTRING,
+    COPILOT_REVIEWER_LOGIN,
+    CURSOR_LOGIN_FILTER_SUBSTRING,
+    GH_REQUESTED_REVIEWERS_PATH_TEMPLATE,
+    GRAPHQL_REVIEW_THREADS_PAGE_SIZE,
+    UNRESOLVED_THREAD_DETAIL_MAX,
+)
+from pr_converge_scripts_constants.convergence_gate_constants import (
+    GRAPHQL_REVIEW_THREADS_QUERY,
+    PENDING_REVIEWER_JOIN_SEPARATOR,
+    THREAD_PATH_JOIN_SEPARATOR,
+)
+
+
+def _gh_graphql(query: str, variables: JsonObject) -> tuple[int, str]:
+    """Run a ``gh api graphql`` query with variables and return returncode and stdout."""
+    all_arguments: list[str] = ["gh", "api", "graphql", "-f", f"query={query}"]
+    for each_key, each_variable in variables.items():
+        if each_variable is None:
+            continue
+        flag = "-F" if isinstance(each_variable, int) else "-f"
+        all_arguments.extend([flag, f"{each_key}={each_variable}"])
+    return _run_gh_command(all_arguments)
+
+
+def _thread_author_login(thread: JsonObject) -> str:
+    """Return the login of a review thread's first comment author, or empty string."""
+    comments_wrapper = thread.get("comments", {})
+    if not isinstance(comments_wrapper, dict):
+        return ""
+    comments_nodes = comments_wrapper.get("nodes", [])
+    if not isinstance(comments_nodes, list) or not comments_nodes:
+        return ""
+    first_comment = comments_nodes[0]
+    author_wrapper = (
+        first_comment.get("author") if isinstance(first_comment, dict) else None
+    )
+    if not isinstance(author_wrapper, dict):
+        return ""
+    login = author_wrapper.get("login", "")
+    return login if isinstance(login, str) else ""
+
+
+def _is_unresolved_bot_thread(thread: JsonObject, bot_logins: ReviewStateGroup) -> bool:
+    """Return whether a review thread is unresolved, current, and bot-authored."""
+    if thread.get("isResolved") is True or thread.get("isOutdated") is True:
+        return False
+    login = _thread_author_login(thread).lower()
+    return any(each_bot in login for each_bot in bot_logins)
+
+
+def _unresolved_bot_threads_in_page(
+    nodes: object, bot_logins: ReviewStateGroup
+) -> list[JsonObject]:
+    """Return the unresolved bot-authored threads among one page of thread nodes."""
+    if not isinstance(nodes, list):
+        return []
+    return [
+        each_thread
+        for each_thread in nodes
+        if isinstance(each_thread, dict)
+        and _is_unresolved_bot_thread(each_thread, bot_logins)
+    ]
+
+
+def _review_threads_container(graphql_payload: object) -> JsonObject | None:
+    """Return the ``reviewThreads`` object from a GraphQL payload, or None."""
+    if not isinstance(graphql_payload, dict):
+        return None
+    envelope = graphql_payload.get("data", {})
+    repository = envelope.get("repository", {}) if isinstance(envelope, dict) else {}
+    pull_request = (
+        repository.get("pullRequest", {}) if isinstance(repository, dict) else {}
+    )
+    threads = (
+        pull_request.get("reviewThreads", {}) if isinstance(pull_request, dict) else {}
+    )
+    return threads if isinstance(threads, dict) else None
+
+
+def _fetch_review_threads_page(
+    *, owner: str, repo: str, number: int, cursor: str | None
+) -> tuple[str, object, object]:
+    """Fetch one page of review threads and return an error text, nodes, and page info."""
+    variables: JsonObject = {
+        "owner": owner,
+        "repo": repo,
+        "number": number,
+        "first": GRAPHQL_REVIEW_THREADS_PAGE_SIZE,
+        "cursor": cursor,
+    }
+    returncode, stdout = _gh_graphql(GRAPHQL_REVIEW_THREADS_QUERY, variables)
+    if returncode != 0:
+        return f"gh api graphql error: {stdout}", [], {}
+    try:
+        graphql_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return "gh api graphql response not valid JSON", [], {}
+    threads = _review_threads_container(graphql_payload)
+    if threads is None:
+        return "unexpected GraphQL response shape", [], {}
+    return "", threads.get("nodes", []), threads.get("pageInfo", {})
+
+
+def _next_thread_cursor(page_info: object) -> str | None:
+    """Return the next pagination cursor, or None when there is no next page."""
+    if not isinstance(page_info, dict):
+        return None
+    if not page_info.get("hasNextPage"):
+        return None
+    next_cursor = page_info.get("endCursor")
+    return next_cursor if isinstance(next_cursor, str) else None
+
+
+def _format_unresolved_detail(all_unresolved: list[JsonObject]) -> str:
+    """Format the unresolved-thread count and a bounded list of their paths."""
+    detail_parts = [
+        str(each_thread.get("path", "?"))
+        for each_thread in all_unresolved[:UNRESOLVED_THREAD_DETAIL_MAX]
+    ]
+    detail_text = THREAD_PATH_JOIN_SEPARATOR.join(detail_parts)
+    if len(all_unresolved) > UNRESOLVED_THREAD_DETAIL_MAX:
+        detail_text += (
+            f" ... and {len(all_unresolved) - UNRESOLVED_THREAD_DETAIL_MAX} more"
+        )
+    return f"{len(all_unresolved)} unresolved ({detail_text})"
+
+
+def _count_unresolved_bot_threads(
+    *, owner: str, repo: str, number: int
+) -> tuple[bool, str]:
+    """Return whether zero unresolved bot review threads remain on the PR."""
+    bot_logins = (
+        CURSOR_LOGIN_FILTER_SUBSTRING,
+        CLAUDE_LOGIN_FILTER_SUBSTRING,
+        COPILOT_LOGIN_FILTER_SUBSTRING,
+    )
+    all_unresolved: list[JsonObject] = []
+    cursor: str | None = None
+    while True:
+        error_text, nodes, page_info = _fetch_review_threads_page(
+            owner=owner, repo=repo, number=number, cursor=cursor
+        )
+        if error_text:
+            return False, error_text
+        all_unresolved.extend(_unresolved_bot_threads_in_page(nodes, bot_logins))
+        cursor = _next_thread_cursor(page_info)
+        if cursor is None:
+            break
+    if not all_unresolved:
+        return True, "0 unresolved"
+    return False, _format_unresolved_detail(all_unresolved)
+
+
+def _requested_reviewer_users(pending_payload: object) -> list[object]:
+    if isinstance(pending_payload, dict):
+        users = pending_payload.get("users", [])
+    elif isinstance(pending_payload, list):
+        users = pending_payload
+    else:
+        return []
+    return users if isinstance(users, list) else []
+
+
+def _pending_copilot_logins(all_users: list[object]) -> list[str]:
+    """Return the Copilot reviewer logins still pending among requested reviewers."""
+    pending: list[str] = []
+    for each_user in all_users:
+        if not isinstance(each_user, dict):
+            continue
+        login = each_user.get("login", "")
+        if isinstance(login, str) and COPILOT_REVIEWER_LOGIN.lower() in login.lower():
+            pending.append(login)
+    return pending
+
+
+def _check_no_pending_reviews(
+    *, owner: str, repo: str, number: int
+) -> tuple[bool, str]:
+    """Return whether no Copilot review request is still pending on the PR."""
+    endpoint = GH_REQUESTED_REVIEWERS_PATH_TEMPLATE.format(
+        owner=owner, repo=repo, number=number
+    )
+    returncode, stdout = _gh_api(endpoint)
+    if returncode != 0:
+        return False, f"gh api error: {stdout}"
+    try:
+        pending_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return False, "pending-reviewers response not valid JSON"
+    copilot_pending = _pending_copilot_logins(
+        _requested_reviewer_users(pending_payload)
+    )
+    if copilot_pending:
+        return (
+            False,
+            f"pending: {PENDING_REVIEWER_JOIN_SEPARATOR.join(copilot_pending)}",
+        )
+    return True, "no pending reviewers"

package/_shared/pr-loop/scripts/check_pending_reviews.py

@@ -0,0 +1,154 @@
+"""Check for pending pull request reviews.
+
+Usage:
+  python scripts/check_pending_reviews.py --owner <O> --repo <R> --pr-number <N> [--user <substring>]
+
+Exit codes:
+  0 — pending review(s) found (printed to stdout as JSON array)
+  1 — no pending reviews found
+  EXIT_CODE_GH_ERROR — gh CLI error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_pr_converge_dir = Path(__file__).absolute().parent.parent
+if str(_pr_converge_dir) not in sys.path:
+    sys.path.insert(0, str(_pr_converge_dir))
+
+from pr_converge_skill_constants.constants import (
+    EXIT_CODE_GH_ERROR,
+    GH_REVIEWS_PATH_TEMPLATE,
+    REVIEWS_PER_PAGE,
+)
+
+
+def fetch_pending_reviews(
+    *, owner: str, repo: str, number: int, user_filter: str | None = None
+) -> list[dict[str, object]]:
+    """Fetch pending reviews for a pull request.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        number: Pull request number.
+        user_filter: Optional case-insensitive substring to match against user login.
+
+    Returns:
+        List of pending review entries.
+
+    Raises:
+        SystemExit: When the gh CLI call fails.
+    """
+    endpoint_path = (
+        GH_REVIEWS_PATH_TEMPLATE.format(owner=owner, repo=repo, number=number)
+        + f"?per_page={REVIEWS_PER_PAGE}"
+    )
+    completed_process = subprocess.run(
+        ["gh", "api", endpoint_path, "--paginate", "--slurp"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if completed_process.returncode != 0:
+        print(f"gh api error: {completed_process.stderr}", file=sys.stderr)
+        raise SystemExit(EXIT_CODE_GH_ERROR)
+    raw_output: object = json.loads(completed_process.stdout)
+    if not isinstance(raw_output, list):
+        return []
+    all_pages: list[list[dict[str, object]]] = [
+        each_page for each_page in raw_output if isinstance(each_page, list)
+    ]
+    all_flat: list[dict[str, object]] = [
+        each_item for each_page in all_pages for each_item in each_page
+    ]
+    pending_reviews: list[dict[str, object]] = []
+    for each_review in all_flat:
+        if each_review.get("state") != "PENDING":
+            continue
+        user_object: object = each_review.get("user")
+        user_login: str = ""
+        if isinstance(user_object, dict):
+            raw_login: object = user_object.get("login")
+            if isinstance(raw_login, str):
+                user_login = raw_login
+        raw_submitted: object = each_review.get("submitted_at")
+        submitted_at: str = ""
+        if isinstance(raw_submitted, str):
+            submitted_at = raw_submitted
+        raw_commit: object = each_review.get("commit_id")
+        commit_short: str = ""
+        if isinstance(raw_commit, str):
+            commit_short = raw_commit[:7]
+        if user_filter is not None and user_filter.lower() not in user_login.lower():
+            continue
+        pending_reviews.append(
+            {
+                "user": user_login,
+                "submitted_at": submitted_at,
+                "commit_id": commit_short,
+            }
+        )
+    return pending_reviews
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with owner, repo, and number.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--owner", required=True, help="GitHub repository owner")
+    parser.add_argument("--repo", required=True, help="GitHub repository name")
+    parser.add_argument("--pr-number", required=True, type=int, help="Pull request number")
+    parser.add_argument(
+        "--user",
+        default=None,
+        help="Optional case-insensitive substring filter for user login",
+    )
+    return parser.parse_args(all_argv)
+
+
+def main(
+    all_arguments: list[str], *, user_filter: str | None = None
+) -> int:
+    """Entry point for check_pending_reviews.
+
+    Args:
+        all_arguments: Command-line arguments.
+        user_filter: Override for user filter (default: from CLI).
+
+    Returns:
+        0 when pending reviews are found, 1 when none, EXIT_CODE_GH_ERROR on error.
+    """
+    arguments = parse_arguments(all_arguments)
+    if arguments.owner is None:
+        return 1
+    pending = fetch_pending_reviews(
+        owner=arguments.owner,
+        repo=arguments.repo,
+        number=getattr(arguments, "pr_number"),
+        user_filter=arguments.user if user_filter is None else user_filter,
+    )
+    if pending:
+        json.dump(pending, sys.stdout)
+        sys.stdout.write("\n")
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    all_argv = sys.argv[1:]
+    arguments = parse_arguments(all_argv)
+    raise SystemExit(main(all_argv, user_filter=arguments.user))

package/_shared/pr-loop/scripts/codex_down_classifier.py

@@ -0,0 +1,98 @@
+"""Classify Codex run streams into down-detail and gate outcome classes.
+
+::
+
+    classification = classify_codex_run(exit_code=1, stream_text=stderr_text)
+    classification.detail_class   # usage_limit | auth_failure | ...
+    classification.outcome_class  # codex_down | completed
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from codex_review_scripts_constants.classifier_constants import (
+    ALL_AUTH_FAILURE_MARKERS,
+    ALL_CONFIG_ERROR_MARKERS,
+    ALL_MODEL_ERROR_MARKERS,
+    ALL_USAGE_LIMIT_MARKERS,
+    FAILURE_CLASS_AUTH_FAILURE,
+    FAILURE_CLASS_CONFIG_ERROR,
+    FAILURE_CLASS_MODEL_ERROR,
+    FAILURE_CLASS_UNKNOWN,
+    FAILURE_CLASS_USAGE_LIMIT,
+    SUCCESS_EXIT_CODE,
+)
+from codex_review_scripts_constants.run_constants import (
+    OUTCOME_CLASS_CODEX_DOWN,
+    OUTCOME_CLASS_COMPLETED,
+)
+
+
+@dataclass(frozen=True)
+class CodexRunClassification:
+    """Fine-grained failure class plus the gate-level outcome class.
+
+    ::
+
+        CodexRunClassification(
+            detail_class="config_error",
+            outcome_class="codex_down",
+        )
+
+    Attributes:
+        detail_class: ``completed`` or a failure class name.
+        outcome_class: ``completed`` or ``codex_down`` for the conditional gate.
+    """
+
+    detail_class: str
+    outcome_class: str
+
+
+def _stream_contains_marker(stream_text: str, all_markers: tuple[str, ...]) -> bool:
+    lowered_stream = stream_text.lower()
+    return any(each_marker in lowered_stream for each_marker in all_markers)
+
+
+def _classify_failure_detail(stream_text: str) -> str:
+    if _stream_contains_marker(stream_text, ALL_CONFIG_ERROR_MARKERS):
+        return FAILURE_CLASS_CONFIG_ERROR
+    if _stream_contains_marker(stream_text, ALL_MODEL_ERROR_MARKERS):
+        return FAILURE_CLASS_MODEL_ERROR
+    if _stream_contains_marker(stream_text, ALL_USAGE_LIMIT_MARKERS):
+        return FAILURE_CLASS_USAGE_LIMIT
+    if _stream_contains_marker(stream_text, ALL_AUTH_FAILURE_MARKERS):
+        return FAILURE_CLASS_AUTH_FAILURE
+    return FAILURE_CLASS_UNKNOWN
+
+
+def classify_codex_run(*, exit_code: int, stream_text: str) -> CodexRunClassification:
+    """Map exit code and stream text to detail and gate outcome classes.
+
+    ::
+
+        classify_codex_run(exit_code=0, stream_text=success_jsonl)
+        # ok: detail_class=completed, outcome_class=completed
+        classify_codex_run(exit_code=1, stream_text="rate limit")
+        # ok: detail_class=usage_limit, outcome_class=codex_down
+
+    Exit zero is a completed review. Every other class — including
+    ``unknown`` for nonzero exits and unparseable text — maps to
+    ``codex_down`` so the conditional gate fails closed.
+
+    Args:
+        exit_code: Process exit code from the Codex review invocation.
+        stream_text: Captured stdout JSONL and/or stderr text.
+
+    Returns:
+        Detail class and gate outcome class for the run.
+    """
+    if exit_code == SUCCESS_EXIT_CODE:
+        return CodexRunClassification(
+            detail_class=OUTCOME_CLASS_COMPLETED,
+            outcome_class=OUTCOME_CLASS_COMPLETED,
+        )
+    return CodexRunClassification(
+        detail_class=_classify_failure_detail(stream_text),
+        outcome_class=OUTCOME_CLASS_CODEX_DOWN,
+    )

package/_shared/pr-loop/scripts/codex_review_scripts_constants/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/_shared/pr-loop/scripts/codex_review_scripts_constants/AGENTS.md

@@ -0,0 +1,18 @@
+# codex_review_scripts_constants
+
+Python package of named constants imported by Codex review scripts under `_shared/pr-loop/scripts/`. Importing from this package keeps magic values out of script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `__init__.py` | Package marker and package docstring. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, and capture outcome class labels for `run_codex_review.py`. |
+| `findings_constants.py` | Finding field keys, fenced-JSON and freeform patterns for `parse_codex_findings.py`. |
+| `classifier_constants.py` | Failure class names and stream markers for `codex_down_classifier.py`. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, JSONL capture filename and newline mode, and capture outcome class labels for `run_codex_review.py`. |
+| `codex_usage_probe_constants.py` | The weekly-usage probe CLI: gate threshold, report JSON keys, app-server JSON-RPC surface, rate-limit field keys, weekly-window sizing, text-status parse patterns, source labels, and exit codes. |
+
+## Convention
+
+Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.

package/_shared/pr-loop/scripts/codex_review_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for Codex review scripts in _shared/pr-loop/scripts."""

package/_shared/pr-loop/scripts/codex_review_scripts_constants/classifier_constants.py

@@ -0,0 +1,35 @@
+"""Named constants for the Codex down-classifier."""
+
+from __future__ import annotations
+
+FAILURE_CLASS_USAGE_LIMIT = "usage_limit"
+FAILURE_CLASS_AUTH_FAILURE = "auth_failure"
+FAILURE_CLASS_CONFIG_ERROR = "config_error"
+FAILURE_CLASS_MODEL_ERROR = "model_error"
+FAILURE_CLASS_UNKNOWN = "unknown"
+ALL_CONFIG_ERROR_MARKERS = (
+    "error loading config.toml",
+    "unknown variant",
+)
+ALL_MODEL_ERROR_MARKERS = (
+    "invalid_request_error",
+    "model is not supported",
+    "requires a newer version of codex",
+)
+ALL_USAGE_LIMIT_MARKERS = (
+    "rate limit",
+    "too many requests",
+    "http 429",
+    " (429)",
+    "credits exhausted",
+    "out of credits",
+    "api quota",
+    "usage quota",
+)
+ALL_AUTH_FAILURE_MARKERS = (
+    "unauthorized",
+    "authentication failed",
+    "login required",
+    "not authenticated",
+)
+SUCCESS_EXIT_CODE = 0

package/_shared/pr-loop/scripts/codex_review_scripts_constants/codex_usage_probe_constants.py

@@ -0,0 +1,82 @@
+"""Constants for the Codex weekly-usage probe CLI.
+
+Groups: gate threshold, probe report JSON keys, app-server JSON-RPC surface,
+rate-limit snapshot field keys, weekly-window sizing, parse patterns for
+text status output, source labels, and exit codes.
+"""
+
+from __future__ import annotations
+
+WEEKLY_USAGE_GATE_THRESHOLD_PERCENT = 10
+
+USAGE_REPORT_KEY_PERCENT_LEFT = "percent_left"
+USAGE_REPORT_KEY_WINDOW_RESET = "window_reset"
+USAGE_REPORT_KEY_SOURCE = "source"
+
+CODEX_BINARY_NAME = "codex"
+ALL_APP_SERVER_COMMAND_PARTS = ("app-server", "--listen", "stdio://")
+APP_SERVER_TIMEOUT_SECONDS = 30
+READER_THREAD_JOIN_TIMEOUT_SECONDS = 2
+PROCESS_TREE_WAIT_TIMEOUT_SECONDS = 5
+WINDOWS_OS_NAME = "nt"
+WINDOWS_COMMAND_SHELL = "cmd"
+WINDOWS_COMMAND_SHELL_RUN_FLAG = "/c"
+ALL_WINDOWS_SCRIPT_SUFFIXES = (".cmd", ".bat")
+
+JSONRPC_VERSION = "2.0"
+JSONRPC_KEY_ID = "id"
+JSONRPC_KEY_METHOD = "method"
+JSONRPC_KEY_PARAMS = "params"
+JSONRPC_KEY_REPLY_BODY = "result"
+JSONRPC_KEY_ERROR = "error"
+JSONRPC_KEY_VERSION = "jsonrpc"
+
+INITIALIZE_REQUEST_ID = 1
+RATE_LIMITS_REQUEST_ID = 2
+METHOD_INITIALIZE = "initialize"
+METHOD_INITIALIZED = "initialized"
+METHOD_RATE_LIMITS_READ = "account/rateLimits/read"
+
+CLIENT_INFO_KEY = "clientInfo"
+CLIENT_INFO_NAME_KEY = "name"
+CLIENT_INFO_VERSION_KEY = "version"
+CLIENT_INFO_NAME = "codex-usage-probe"
+CLIENT_INFO_VERSION = "1.0.0"
+CAPABILITIES_KEY = "capabilities"
+EXPERIMENTAL_API_KEY = "experimentalApi"
+
+RATE_LIMITS_KEY = "rateLimits"
+PRIMARY_WINDOW_KEY = "primary"
+SECONDARY_WINDOW_KEY = "secondary"
+USED_PERCENT_KEY = "usedPercent"
+RESETS_AT_KEY = "resetsAt"
+WINDOW_DURATION_MINS_KEY = "windowDurationMins"
+
+WEEKLY_WINDOW_DURATION_MINUTES = 10080
+PERCENT_FULL = 100
+PERCENT_EMPTY = 0
+
+SOURCE_APP_SERVER_RATE_LIMITS = "codex app-server account/rateLimits/read"
+SOURCE_TEXT_STATUS = "text-status"
+SOURCE_NO_USAGE_SURFACE = "no-usage-surface"
+
+TEXT_WEEKLY_PERCENT_LEFT_PATTERN = (
+    r"(?i)weekly(?:\s+(?:limit|usage|cap))?"
+    r"[^\n%]{0,40}?"
+    r"(?P<percent>\d{1,3}(?:\.\d+)?)\s*%\s*(?:left|remaining)"
+)
+TEXT_WEEKLY_USED_PERCENT_PATTERN = (
+    r"(?i)weekly(?:\s+(?:limit|usage|cap))?"
+    r"[^\n%]{0,40}?"
+    r"(?P<percent>\d{1,3}(?:\.\d+)?)\s*%\s*(?:used|consumed)"
+)
+TEXT_WINDOW_RESET_PATTERN = (
+    r"(?i)(?:weekly\s+)?(?:window\s+)?resets?(?:\s+at)?"
+    r"[:\s]+(?P<reset>[^\s)\].,;]+)"
+)
+
+EXIT_CODE_SUCCESS = 0
+EXIT_CODE_CRASH = 1
+
+UTF8_ENCODING = "utf-8"
+NEWLINE = "\n"

package/_shared/pr-loop/scripts/codex_review_scripts_constants/findings_constants.py

@@ -0,0 +1,18 @@
+"""Named constants for the Codex findings parser."""
+
+from __future__ import annotations
+
+FINDING_KEY_TITLE = "title"
+FINDING_KEY_PRIORITY = "priority"
+FINDING_KEY_FILE = "file"
+FINDING_KEY_LINE_RANGE = "line_range"
+FINDING_KEY_BODY = "body"
+FENCED_JSON_BLOCK_PATTERN = r"```(?:json)?\s*\n(.*?)\n```"
+FREEFORM_FINDING_LINE_PATTERN = (
+    r"^-\s*\[(?P<priority>P\d+)\]\s+"
+    r"(?P<title>.+?)\s+[—–-]\s+"
+    r"(?P<file_path>.+?):(?P<line_range>\d+-\d+)\s*$"
+)
+FREEFORM_BULLET_PREFIX = "- ["
+EMPTY_STRING = ""
+NEWLINE = "\n"

package/_shared/pr-loop/scripts/codex_review_scripts_constants/run_constants.py

@@ -0,0 +1,53 @@
+"""Named constants for the Codex review headless wrapper."""
+
+from __future__ import annotations
+
+CODEX_BINARY_NAME = "codex"
+EXEC_SUBCOMMAND = "exec"
+REVIEW_SUBCOMMAND = "review"
+HELP_FLAG = "--help"
+VERSION_FLAG = "--version"
+JSON_FLAG = "--json"
+BASE_TARGET_FLAG = "--base"
+UNCOMMITTED_TARGET_FLAG = "--uncommitted"
+COMMIT_TARGET_FLAG = "--commit"
+MODEL_FLAG = "-m"
+CODEX_MODEL_PIN = ""
+CODEX_HOME_ENV_VAR = "CODEX_HOME"
+DEFAULT_TIMEOUT_SECONDS = 600
+JSONL_CAPTURE_FILENAME = "codex-review.jsonl"
+JSONL_CAPTURE_NEWLINE = ""
+UTF8_ENCODING = "utf-8"
+VERSION_PROBE_PATTERN = r"codex(?:-cli)?\s+(\d+\.\d+\.\d+)"
+OUTCOME_CLASS_CODEX_DOWN = "codex_down"
+OUTCOME_CLASS_COMPLETED = "completed"
+MISSING_BINARY_EXIT_CODE = 127
+TIMEOUT_EXIT_CODE = 124
+SUBPROCESS_DECODE_EXIT_CODE = 70
+CWD_KEYWORD = "cwd"
+CAPTURE_STREAMS_KEYWORD = "capture_output"
+TEXT_MODE_KEYWORD = "text"
+ENCODING_KEYWORD = "encoding"
+CHECK_KEYWORD = "check"
+TIMEOUT_KEYWORD = "timeout"
+ENVIRONMENT_KEYWORD = "env"
+PROCESS_TREE_KILL_TIMEOUT_SECONDS = 10
+SHAPE_FLAG_TOKEN_TAIL_PATTERN = r"(?![\w-])"
+JSONL_EVENT_TYPE_KEY = "type"
+JSONL_ENTRY_KEY = "item"
+JSONL_ENTRY_COMPLETED_TYPE = "item.completed"
+JSONL_AGENT_MESSAGE_TYPE = "agent_message"
+JSONL_AGENT_MESSAGE_TEXT_KEY = "text"
+CUSTOM_INSTRUCTIONS_PROMPT = (
+    "Write a one-line review summary, then the heading Review comment:, then "
+    "zero or more finding bullets. Each bullet must use the form "
+    "- [P1] <title> — <path>:<start>-<end> "
+    "followed by an explanation paragraph. Use the same [P#] priority tags. "
+    "When there are no findings, omit finding bullets after the summary."
+)
+ALL_SHAPE_PROBE_REQUIRED_FLAGS = (
+    BASE_TARGET_FLAG,
+    UNCOMMITTED_TARGET_FLAG,
+    COMMIT_TARGET_FLAG,
+    JSON_FLAG,
+)