claude-dev-env 8.29.0 → 8.30.0

package/.agents/skills/codex-cleanse/config/constants.test.mjs

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+    DEFAULT_INACTIVE_DAYS,
+    MILLISECONDS_PER_DAY,
+    MILLISECONDS_PER_SECOND,
+    PAGE_SIZE,
+    REQUEST_TIMEOUT_MILLISECONDS,
+    ROLLOUT_FILENAME_PATTERN,
+    SOURCE_KINDS,
+    THREAD_ID_PATTERN,
+} from './constants.mjs';
+
+test('cleanse defaults to a seven-day cutoff and bounded requests', () => {
+    assert.equal(DEFAULT_INACTIVE_DAYS, 7);
+    assert.equal(MILLISECONDS_PER_DAY, 86_400_000);
+    assert.equal(MILLISECONDS_PER_SECOND, 1_000);
+    assert.equal(PAGE_SIZE, 1_000);
+    assert.equal(REQUEST_TIMEOUT_MILLISECONDS, 30_000);
+});
+
+test('session listing includes every supported source kind', () => {
+    assert.deepEqual(SOURCE_KINDS, [
+        'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview',
+        'subAgentCompact', 'subAgentThreadSpawn', 'subAgentOther', 'unknown',
+    ]);
+});
+
+test('thread IDs accept UUID spelling and reject malformed IDs', () => {
+    assert.equal(THREAD_ID_PATTERN.test('12345678-1234-ABCD-1234-123456789ABC'), true);
+    assert.equal(THREAD_ID_PATTERN.test('12345678-1234-ABCD-1234-123456789AB'), false);
+    assert.equal(THREAD_ID_PATTERN.test('prefix-12345678-1234-ABCD-1234-123456789ABC'), false);
+});
+
+test('rollout filenames yield the thread ID and reject other files', () => {
+    const threadId = '12345678-1234-ABCD-1234-123456789ABC';
+    const filename = `rollout-2026-09-30T12-34-56-${threadId}.jsonl`;
+    assert.equal(ROLLOUT_FILENAME_PATTERN.exec(filename)?.[1], threadId);
+    assert.equal(ROLLOUT_FILENAME_PATTERN.test(`${filename}.bak`), false);
+    assert.equal(ROLLOUT_FILENAME_PATTERN.test(`other-${filename}`), false);
+});

package/.agents/skills/e-code-review/SKILL.md

@@ -36,6 +36,21 @@ Each level file reports through the ReportFindings tool. When the host has no Re
 
 ## The process
 
+### Native GitHub evidence pilot
+
+Keep one coordinator responsible for native review requests. Record the request comment and full candidate head. Read raw GitHub review records to retain commit_id; normalized connector output can omit it. Completed reviews can contain findings. The quota_notice_ids field records historical usage-limit comments. Driver replies and resolved threads provide no clean completion proof.
+
+Use process-local GITHUB_TOKEN or GH_TOKEN authentication without printing credentials. A code-review usage-limit response stops further triggers until capacity is verified. Preserve the hold; review permission changes and credit purchases require separate authorization. Capture API bytes as UTF-8 before decoding them so Windows shell output encoding preserves review headings.
+
+Inspect a candidate from the shared source checkout:
+
+```powershell
+python packages/claude-dev-env/scripts/codex_review_observer.py <owner/repository> <pull-request> <full-head>
+python -m pytest packages/claude-dev-env/scripts/tests/test_codex_review_observer.py packages/claude-dev-env/scripts/tests/test_codex_review_guidance.py -q --override-ini="addopts=" -p no:cacheprovider
+```
+
+The current observer holds admission for every supported diagnostic. Require captured successful native completion with full-head and attempt coverage before adding a clean verdict. After a repair push, review the new head and preserve all existing checks. Keep current repository contracts authoritative over copied hosted policy.
+
 1. Read the level and the optional `--fix` flag. Load the level file.
 2. Run it end to end, ending in its ReportFindings call.
 3. With `--fix`, load `reference/fix.md` and run it on those findings.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.29.0",
+    "version": "8.30.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/codex_review_observer.py

@@ -0,0 +1,285 @@
+"""Observe candidate reviews without granting admission to a merge queue.
+
+Native completion representation and reviewer identity remain unverified.
+Every observation holds admission, including plausible success records.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from urllib.error import URLError
+
+from dev_env_scripts_constants.codex_review_observer_constants import (
+    CODEX_FINDINGS_HEADING,
+    CODEX_FINDINGS_PREFIX,
+    CODEX_QUOTA_PREFIX,
+    CODEX_REVIEWER_LOGIN,
+    COMMENTS_URL,
+    COMMIT_PATTERN,
+    HOLD_EXIT_CODE,
+    MAX_PAGES,
+    PAGE_SIZE,
+    PULL_URL,
+    REPOSITORY_PATTERN,
+    REVIEWS_SUFFIX,
+    UNAVAILABLE_EXIT_CODE,
+)
+from pr_verification.github_parsing import GitHubError
+from review_closure_github import github_token, request_json
+
+GitHubRead = Callable[[str], object]
+
+
+class HoldReason(str, Enum):
+    MISSING_REVIEW = "missing_review"
+    STALE_REVIEW = "stale_review"
+    HEAD_CHANGED = "head_changed"
+    NATIVE_FORMAT_UNVERIFIED = "native_format_unverified"
+    READ_UNAVAILABLE = "read_unavailable"
+    READ_TIMEOUT = "read_timeout"
+    INCOMPLETE_READ = "incomplete_read"
+    CONFLICTING_EVIDENCE = "conflicting_evidence"
+    REVIEW_FINDINGS = "review_findings"
+    QUOTA_NOTICE = "quota_notice"
+
+
+@dataclass(frozen=True)
+class Candidate:
+    repository: str
+    pull_request: int
+    head_sha: str
+
+    def __post_init__(self) -> None:
+        if (
+            re.fullmatch(REPOSITORY_PATTERN, self.repository) is None
+            or type(self.pull_request) is not int
+            or self.pull_request <= 0
+            or re.fullmatch(COMMIT_PATTERN, self.head_sha) is None
+        ):
+            raise ValueError("A repository, pull request, and full head are required.")
+
+
+@dataclass(frozen=True)
+class ReviewObservation:
+    candidate: Candidate
+    reason: HoldReason
+    evidence_ids: tuple[int, ...] = ()
+    quota_notice_ids: tuple[int, ...] = ()
+
+
+def _matches_candidate(document: object, candidate: Candidate) -> bool:
+    if not isinstance(document, Mapping):
+        return False
+    head = document.get("head")
+    return (
+        document.get("number") == candidate.pull_request
+        and isinstance(head, Mapping)
+        and head.get("sha") == candidate.head_sha
+    )
+
+
+def _is_submitted_codex_findings(all_review: Mapping[str, object]) -> bool:
+    author = all_review.get("user")
+    body = all_review.get("body")
+    submitted_at = all_review.get("submitted_at")
+    if not (
+        isinstance(author, Mapping)
+        and author.get("login") == CODEX_REVIEWER_LOGIN
+        and all_review.get("state") == "COMMENTED"
+        and isinstance(body, str)
+        and body.lstrip().startswith((CODEX_FINDINGS_PREFIX, CODEX_FINDINGS_HEADING))
+        and isinstance(submitted_at, str)
+    ):
+        return False
+    try:
+        return datetime.fromisoformat(submitted_at).tzinfo is not None
+    except ValueError:
+        return False
+
+
+class _EvidenceReadRunFatal(Exception):
+    def __init__(self, reason: HoldReason) -> None:
+        super().__init__(reason.value)
+        self.reason = reason
+
+
+def _merge_page(all_records: dict[int, Mapping[str, object]], all_page: object) -> int:
+    if not isinstance(all_page, list):
+        raise _EvidenceReadRunFatal(HoldReason.INCOMPLETE_READ)
+    for each_record in all_page:
+        if not isinstance(each_record, Mapping):
+            raise _EvidenceReadRunFatal(HoldReason.INCOMPLETE_READ)
+        record_id = each_record.get("id")
+        if type(record_id) is not int or record_id <= 0:
+            raise _EvidenceReadRunFatal(HoldReason.INCOMPLETE_READ)
+        if record_id in all_records and all_records[record_id] != each_record:
+            raise _EvidenceReadRunFatal(HoldReason.CONFLICTING_EVIDENCE)
+        all_records[record_id] = each_record
+    return len(all_page)
+
+
+def _read_collection(url: str, read: GitHubRead) -> dict[int, Mapping[str, object]]:
+    all_records: dict[int, Mapping[str, object]] = {}
+    for each_page in range(1, MAX_PAGES + 1):
+        count = _merge_page(
+            all_records, read(f"{url}?per_page={PAGE_SIZE}&page={each_page}")
+        )
+        if count < PAGE_SIZE:
+            return all_records
+    raise _EvidenceReadRunFatal(HoldReason.INCOMPLETE_READ)
+
+
+def _quota_notice_ids(
+    all_comments: Mapping[int, Mapping[str, object]],
+) -> tuple[int, ...]:
+    all_ids: list[int] = []
+    for each_id, each_comment in all_comments.items():
+        author = each_comment.get("user")
+        body = each_comment.get("body")
+        if (
+            isinstance(author, Mapping)
+            and author.get("login") == CODEX_REVIEWER_LOGIN
+            and isinstance(body, str)
+            and body.startswith(CODEX_QUOTA_PREFIX)
+        ):
+            all_ids.append(each_id)
+    return tuple(sorted(all_ids))
+
+
+def _review_observation(
+    candidate: Candidate, all_reviews: Mapping[int, Mapping[str, object]]
+) -> ReviewObservation:
+    all_current = {
+        each_id: each_review
+        for each_id, each_review in all_reviews.items()
+        if each_review.get("commit_id") == candidate.head_sha
+    }
+    reason = HoldReason.MISSING_REVIEW
+    if all_reviews:
+        reason = HoldReason.STALE_REVIEW
+    if all_current:
+        reason = HoldReason.NATIVE_FORMAT_UNVERIFIED
+    if any(
+        _is_submitted_codex_findings(each_review)
+        for each_review in all_current.values()
+    ):
+        reason = HoldReason.REVIEW_FINDINGS
+    return ReviewObservation(candidate, reason, tuple(sorted(all_current)))
+
+
+def _stable_observation(
+    candidate: Candidate, read: GitHubRead, pull_url: str
+) -> ReviewObservation:
+    all_reviews = _read_collection(pull_url + REVIEWS_SUFFIX, read)
+    observation = _review_observation(candidate, all_reviews)
+    comments_url = COMMENTS_URL.format(
+        repository=candidate.repository, number=candidate.pull_request
+    )
+    all_quota_ids = _quota_notice_ids(_read_collection(comments_url, read))
+    reason = observation.reason
+    if all_quota_ids and reason in (
+        HoldReason.MISSING_REVIEW,
+        HoldReason.STALE_REVIEW,
+    ):
+        reason = HoldReason.QUOTA_NOTICE
+    return ReviewObservation(candidate, reason, observation.evidence_ids, all_quota_ids)
+
+
+def _transport_failure_reason(failure: BaseException) -> HoldReason:
+    cause = failure.__cause__
+    if isinstance(failure, TimeoutError) or isinstance(cause, TimeoutError):
+        return HoldReason.READ_TIMEOUT
+    if isinstance(cause, URLError) and isinstance(cause.reason, TimeoutError):
+        return HoldReason.READ_TIMEOUT
+    return HoldReason.READ_UNAVAILABLE
+
+
+def observe_codex_review(candidate: Candidate, read: GitHubRead) -> ReviewObservation:
+    """Read evidence for a stable full head and return its admission hold.
+
+    Args:
+        candidate: The repository, pull request, and requested full head.
+        read: Authenticated read-only JSON transport.
+
+    Returns:
+        The observed hold and evidence identifiers.
+    """
+    pull_url = PULL_URL.format(
+        repository=candidate.repository, number=candidate.pull_request
+    )
+    observation = ReviewObservation(candidate, HoldReason.MISSING_REVIEW)
+    try:
+        if not _matches_candidate(read(pull_url), candidate):
+            return ReviewObservation(candidate, HoldReason.HEAD_CHANGED)
+        try:
+            observation = _stable_observation(candidate, read, pull_url)
+        except _EvidenceReadRunFatal as failure:
+            observation = ReviewObservation(candidate, failure.reason)
+        if not _matches_candidate(read(pull_url), candidate):
+            return ReviewObservation(candidate, HoldReason.HEAD_CHANGED)
+    except TimeoutError:
+        return ReviewObservation(candidate, HoldReason.READ_TIMEOUT)
+    except (GitHubError, OSError) as failure:
+        return ReviewObservation(candidate, _transport_failure_reason(failure))
+    return observation
+
+
+def _observation_document(observation: ReviewObservation) -> dict[str, object]:
+    candidate = observation.candidate
+    return {
+        "repository": candidate.repository,
+        "pull_request": candidate.pull_request,
+        "head_sha": candidate.head_sha,
+        "admission": "hold",
+        "reason": observation.reason.value,
+        "evidence_ids": observation.evidence_ids,
+        "quota_notice_ids": observation.quota_notice_ids,
+    }
+
+
+def _parse_candidate(all_arguments: Sequence[str]) -> Candidate:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("repository")
+    parser.add_argument("pull_request", type=int)
+    parser.add_argument("head_sha")
+    parsed = parser.parse_args(all_arguments)
+    return Candidate(parsed.repository, parsed.pull_request, parsed.head_sha)
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Print a read-only observation and return nonzero for every hold.
+
+    Args:
+        all_arguments: Command arguments without the executable name.
+
+    Returns:
+        One for a hold, or two when the read is unavailable.
+    """
+    try:
+        candidate = _parse_candidate(all_arguments)
+        token = github_token()
+    except (ValueError, GitHubError) as failure:
+        print(str(failure), file=sys.stderr)
+        return UNAVAILABLE_EXIT_CODE
+
+    def read(url: str) -> object:
+        return request_json("GET", url, token, None)
+
+    observation = observe_codex_review(candidate, read)
+    print(json.dumps(_observation_document(observation)))
+    return (
+        UNAVAILABLE_EXIT_CODE
+        if observation.reason in (HoldReason.READ_TIMEOUT, HoldReason.READ_UNAVAILABLE)
+        else HOLD_EXIT_CODE
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/codex_review_observer_constants.py

@@ -0,0 +1,17 @@
+"""Bounds for read-only Codex review observations."""
+
+GITHUB_API_ROOT = "https://api.github.com"
+PAGE_SIZE = 100
+MAX_PAGES = 20
+COMMIT_PATTERN = r"[0-9a-f]{40}"
+REPOSITORY_PATTERN = r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+"
+HOLD_EXIT_CODE = 1
+UNAVAILABLE_EXIT_CODE = 2
+CODEX_REVIEWER_LOGIN = "chatgpt-codex-connector[bot]"
+CODEX_FINDINGS_PREFIX = "Here are some automated review suggestions"
+CODEX_FINDINGS_HEADING = "### 💡 Codex Review\n\n" + CODEX_FINDINGS_PREFIX
+
+PULL_URL = GITHUB_API_ROOT + "/repos/{repository}/pulls/{number}"
+COMMENTS_URL = GITHUB_API_ROOT + "/repos/{repository}/issues/{number}/comments"
+REVIEWS_SUFFIX = "/reviews"
+CODEX_QUOTA_PREFIX = "You have reached your Codex usage limits for code reviews."

package/scripts/tests/fixtures/codex-pilot-findings.json

@@ -0,0 +1,14 @@
+{
+  "repository": "jl-cmd/claude-dev-env",
+  "pull_request": 1576,
+  "review": {
+    "id": 5360553725,
+    "state": "COMMENTED",
+    "commit_id": "d66450a145554778c9938c310cae61cca5927884",
+    "submitted_at": "2026-09-30T01:50:30Z",
+    "body": "\n### \ud83d\udca1 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `d66450a145`\n    \n\n<details> <summary>\u2139\ufe0f About Codex in GitHub</summary>\n<br/>\n\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\n- Open a pull request for review\n- Mark a draft as ready\n- Comment \"@codex review\".\n\nIf Codex has suggestions, it will comment; otherwise it will react with \ud83d\udc4d.\n\n\n\n\nCodex can also answer questions or update the PR. Try commenting \"@codex address that feedback\".\n            \n</details>",
+    "user": {
+      "login": "chatgpt-codex-connector[bot]"
+    }
+  }
+}

package/scripts/tests/fixtures/codex-quota-comment.json

@@ -0,0 +1,8 @@
+{
+  "body": "You have reached your Codex usage limits for code reviews. You can see your limits in the [Codex usage dashboard](https://chatgpt.com/codex/cloud/settings/usage).",
+  "created_at": "2026-09-30T00:12:01Z",
+  "id": 5901476928,
+  "user": {
+    "login": "chatgpt-codex-connector[bot]"
+  }
+}

package/scripts/tests/fixtures/codex-quota-credits-comment.json

@@ -0,0 +1,8 @@
+{
+  "body": "You have reached your Codex usage limits for code reviews. You can see your limits in the [Codex usage dashboard](https://chatgpt.com/codex/cloud/settings/usage).\nTo continue using code reviews, add credits to your account and enable them for code reviews in your [settings](https://chatgpt.com/codex/cloud/settings/code-review).",
+  "created_at": "2026-09-30T01:50:30Z",
+  "id": 5902483341,
+  "user": {
+    "login": "chatgpt-codex-connector[bot]"
+  }
+}

package/scripts/tests/fixtures/codex-submitted-findings.json

@@ -0,0 +1,15 @@
+{
+  "provenance": "Fields verified by the parent coordinator from the raw authenticated API. Body contains only the verified prefix. Repository identity is anonymized for the shared package; review fields are unchanged.",
+  "repository": "owner/repository",
+  "pull_request": 4743,
+  "review": {
+    "id": 5322799208,
+    "user": {
+      "login": "chatgpt-codex-connector[bot]"
+    },
+    "state": "COMMENTED",
+    "commit_id": "bed23717ab2ea352113c8f2058fbc959464bdf43",
+    "submitted_at": "2026-09-25T21:15:07Z",
+    "body": "Here are some automated review suggestions"
+  }
+}

package/scripts/tests/test_codex_review_guidance.py

@@ -0,0 +1,15 @@
+"""Native guidance has a repository entry point and stays repository-independent."""
+
+from pathlib import Path
+
+
+def test_native_guidance_is_discoverable() -> None:
+    repository = Path(__file__).resolve().parents[4]
+    instructions = (repository / "AGENTS.md").read_text(encoding="utf-8")
+    assert "# Code Review Rules" in instructions
+    assert "docs/review/review.md" in instructions
+    guidance = (repository / "docs/review/review.md").read_text(encoding="utf-8")
+    assert "Current repository instructions override stale hosted copies." in guidance
+    assert "Completed review can contain findings." in guidance
+    assert "theme_db_id" not in guidance
+    assert "saved-grid" not in guidance

package/scripts/tests/test_codex_review_observer.py

@@ -0,0 +1,357 @@
+"""Refusal behavior for native review evidence whose success format is unknown."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parents[1]
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+import codex_review_observer as observer
+import review_closure_github
+from pr_verification.github_parsing import GitHubError
+
+HEAD = "a" * 40
+NEXT_HEAD = "b" * 40
+CANDIDATE = observer.Candidate("owner/repository", 7, HEAD)
+
+
+def observe(
+    all_pages: list[object], after_head: str = HEAD
+) -> observer.ReviewObservation:
+    all_reads: list[object] = [
+        {"number": 7, "head": {"sha": HEAD}},
+        *all_pages,
+        {"number": 7, "head": {"sha": after_head}},
+    ]
+
+    def read(url: str) -> object:
+        if "/issues/7/comments?" in url:
+            return []
+        assert url.startswith("https://api.github.com/repos/owner/repository/pulls/7")
+        return all_reads.pop(0)
+
+    return observer.observe_codex_review(CANDIDATE, read)
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        "No findings. Review completed successfully.",
+        "Fixed in the next push.",
+        "Review resolved.",
+        "Codex cloud task completed.",
+        "You've reached your Codex code review usage limits.",
+    ],
+)
+def test_body_text_never_authorizes_merge(body: str) -> None:
+    review = {"id": 1, "commit_id": HEAD, "state": "APPROVED", "body": body}
+    observed = observe([[review]])
+    assert observed.reason is observer.HoldReason.NATIVE_FORMAT_UNVERIFIED
+    assert observed.evidence_ids == (1,)
+
+
+def test_missing_review_holds() -> None:
+    assert observe([[]]).reason is observer.HoldReason.MISSING_REVIEW
+
+
+def test_stale_completion_holds() -> None:
+    review = {"id": 1, "commit_id": NEXT_HEAD, "state": "APPROVED"}
+    assert observe([[review]]).reason is observer.HoldReason.STALE_REVIEW
+
+
+def test_head_movement_invalidates_observation() -> None:
+    review = {"id": 1, "commit_id": HEAD, "state": "APPROVED"}
+    assert observe([[review]], NEXT_HEAD).reason is observer.HoldReason.HEAD_CHANGED
+
+
+@pytest.mark.parametrize(
+    "state", ["PENDING", "DISMISSED", "FAILED", "CANCELLED", "SKIPPED"]
+)
+def test_unsuccessful_state_holds(state: str) -> None:
+    review = {"id": 1, "commit_id": HEAD, "state": state}
+    assert observe([[review]]).reason is observer.HoldReason.NATIVE_FORMAT_UNVERIFIED
+
+
+def test_identical_duplicates_are_idempotent() -> None:
+    review = {"id": 1, "commit_id": HEAD, "body": "No findings"}
+    assert observe([[review, review]]).evidence_ids == (1,)
+
+
+def test_conflicting_duplicate_cannot_pass() -> None:
+    first = {"id": 1, "commit_id": HEAD, "body": "No findings"}
+    later = {**first, "body": "A finding remains"}
+    assert observe([[first, later]]).reason is observer.HoldReason.CONFLICTING_EVIDENCE
+
+
+def test_delayed_success_cannot_override_newer_failure() -> None:
+    failed = {"id": 2, "commit_id": HEAD, "state": "FAILED"}
+    delayed = {"id": 1, "commit_id": HEAD, "state": "APPROVED"}
+    assert (
+        observe([[failed, delayed]]).reason
+        is observer.HoldReason.NATIVE_FORMAT_UNVERIFIED
+    )
+
+
+@pytest.mark.parametrize(
+    "failure", [TimeoutError(), GitHubError("quota unavailable"), OSError()]
+)
+def test_transport_failure_holds(failure: Exception) -> None:
+    def read(url: str) -> object:
+        raise failure
+
+    observed = observer.observe_codex_review(CANDIDATE, read)
+    assert observed.reason in (
+        observer.HoldReason.READ_TIMEOUT,
+        observer.HoldReason.READ_UNAVAILABLE,
+    )
+
+
+@pytest.mark.parametrize("page", [None, {}, [None], [{"id": "1"}]])
+def test_malformed_review_collection_holds(page: object) -> None:
+    assert observe([page]).reason is observer.HoldReason.INCOMPLETE_READ
+
+
+def test_incomplete_pagination_holds(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(observer, "MAX_PAGES", 1)
+    all_reviews = [{"id": each_id + 1, "commit_id": HEAD} for each_id in range(100)]
+    assert observe([all_reviews]).reason is observer.HoldReason.INCOMPLETE_READ
+
+
+@pytest.mark.parametrize("head", ["abc123", "A" * 40, "a" * 39])
+def test_candidate_requires_full_head(head: str) -> None:
+    with pytest.raises(ValueError):
+        observer.Candidate("owner/repository", 7, head)
+
+
+def test_wrong_pull_request_is_a_hold() -> None:
+    def read(url: str) -> object:
+        return {"number": 8, "head": {"sha": HEAD}}
+
+    assert (
+        observer.observe_codex_review(CANDIDATE, read).reason
+        is observer.HoldReason.HEAD_CHANGED
+    )
+
+
+def test_cli_returns_nonzero_with_plausible_success(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(observer, "github_token", lambda: "test-token")
+    all_reads = iter(
+        [
+            {"number": 7, "head": {"sha": HEAD}},
+            [{"id": 1, "commit_id": HEAD, "state": "APPROVED"}],
+            [],
+            {"number": 7, "head": {"sha": HEAD}},
+        ]
+    )
+    monkeypatch.setattr(observer, "request_json", lambda *arguments: next(all_reads))
+    assert observer.main(["owner/repository", "7", HEAD]) == 1
+    assert '"admission": "hold"' in capsys.readouterr().out
+
+
+def test_parent_verified_submitted_findings_hold() -> None:
+    fixture_path = Path(__file__).parent / "fixtures/codex-submitted-findings.json"
+    captured = json.loads(fixture_path.read_text(encoding="utf-8"))
+    review = captured["review"]
+    candidate = observer.Candidate(
+        captured["repository"], captured["pull_request"], review["commit_id"]
+    )
+    all_reads = iter(
+        [
+            {"number": candidate.pull_request, "head": {"sha": candidate.head_sha}},
+            [review],
+            [],
+            {"number": candidate.pull_request, "head": {"sha": candidate.head_sha}},
+        ]
+    )
+    observed = observer.observe_codex_review(candidate, lambda url: next(all_reads))
+    assert observed.reason is observer.HoldReason.REVIEW_FINDINGS
+    assert observed.evidence_ids == (5322799208,)
+
+
+def test_native_pilot_heading_preserves_findings_hold() -> None:
+    captured = json.loads(
+        (Path(__file__).parent / "fixtures/codex-pilot-findings.json").read_text(
+            encoding="utf-8-sig"
+        )
+    )
+    review = captured["review"]
+    candidate = observer.Candidate(
+        captured["repository"], captured["pull_request"], review["commit_id"]
+    )
+    all_reads = iter(
+        [
+            {"number": candidate.pull_request, "head": {"sha": candidate.head_sha}},
+            [review],
+            [],
+            {"number": candidate.pull_request, "head": {"sha": candidate.head_sha}},
+        ]
+    )
+    observed = observer.observe_codex_review(candidate, lambda url: next(all_reads))
+    assert observed.reason is observer.HoldReason.REVIEW_FINDINGS
+    assert observed.evidence_ids == (5360553725,)
+
+
+def test_cli_production_transport_preserves_timeout(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def timed_out(*args: object, **kwargs: object) -> object:
+        raise TimeoutError("socket read timed out")
+
+    monkeypatch.setattr(observer, "github_token", lambda: "test-token")
+    monkeypatch.setattr(review_closure_github.urllib.request, "urlopen", timed_out)
+    assert observer.main(["owner/repository", "7", HEAD]) == 2
+    assert json.loads(capsys.readouterr().out)["reason"] == "read_timeout"
+
+
+def test_findings_text_from_wrong_actor_stays_unsupported() -> None:
+    review = {
+        "id": 1,
+        "commit_id": HEAD,
+        "state": "COMMENTED",
+        "submitted_at": "2026-09-25T21:15:07Z",
+        "user": {"login": "unrelated-reviewer"},
+        "body": observer.CODEX_FINDINGS_PREFIX,
+    }
+    assert observe([[review]]).reason is observer.HoldReason.NATIVE_FORMAT_UNVERIFIED
+
+
+@pytest.mark.parametrize("actor", [observer.CODEX_REVIEWER_LOGIN, "other-user"])
+@pytest.mark.parametrize(
+    "fixture_name", ["codex-quota-comment.json", "codex-quota-credits-comment.json"]
+)
+def test_authentic_quota_comment_is_diagnostic_only(
+    actor: str, fixture_name: str
+) -> None:
+    comment = json.loads(
+        (Path(__file__).parent / "fixtures" / fixture_name).read_text(
+            encoding="utf-8-sig"
+        )
+    )
+    comment["user"]["login"] = actor
+
+    def read(url: str) -> object:
+        if "/reviews?" in url:
+            return []
+        if "/comments?" in url:
+            return [comment]
+        return {"number": 7, "head": {"sha": HEAD}}
+
+    observed = observer.observe_codex_review(CANDIDATE, read)
+    assert observed.reason is (
+        observer.HoldReason.QUOTA_NOTICE
+        if actor == observer.CODEX_REVIEWER_LOGIN
+        else observer.HoldReason.MISSING_REVIEW
+    )
+    assert observed.evidence_ids == ()
+    assert observed.quota_notice_ids == (
+        (comment["id"],) if actor == observer.CODEX_REVIEWER_LOGIN else ()
+    )
+
+
+@pytest.mark.parametrize(
+    "response,reason",
+    [
+        ({}, observer.HoldReason.INCOMPLETE_READ),
+        ([None], observer.HoldReason.INCOMPLETE_READ),
+        (TimeoutError(), observer.HoldReason.READ_TIMEOUT),
+        (GitHubError("comments unavailable"), observer.HoldReason.READ_UNAVAILABLE),
+        (OSError(), observer.HoldReason.READ_UNAVAILABLE),
+    ],
+)
+@pytest.mark.parametrize("has_current_review", [False, True])
+def test_quota_comment_read_failure_holds(
+    response: object, reason: observer.HoldReason, has_current_review: bool
+) -> None:
+    def read(url: str) -> object:
+        if "/reviews?" in url:
+            return [{"id": 1, "commit_id": HEAD}] if has_current_review else []
+        if "/comments?" in url:
+            if isinstance(response, Exception):
+                raise response
+            return response
+        return {"number": 7, "head": {"sha": HEAD}}
+
+    observed = observer.observe_codex_review(CANDIDATE, read)
+    assert observed.reason is reason
+    assert observed.evidence_ids == ()
+    assert observed.quota_notice_ids == ()
+
+
+@pytest.mark.parametrize("has_findings", [False, True])
+@pytest.mark.parametrize("head_changes", [False, True])
+def test_current_review_preserves_historical_quota_notices(
+    has_findings: bool, head_changes: bool
+) -> None:
+    captured = json.loads(
+        (Path(__file__).parent / "fixtures/codex-pilot-findings.json").read_text(
+            encoding="utf-8-sig"
+        )
+    )
+    review = captured["review"]
+    if not has_findings:
+        review = {
+            "id": 42,
+            "commit_id": review["commit_id"],
+            "state": "APPROVED",
+            "user": {"login": "human-reviewer"},
+        }
+    candidate = observer.Candidate(
+        captured["repository"], captured["pull_request"], review["commit_id"]
+    )
+    comment = json.loads(
+        (Path(__file__).parent / "fixtures/codex-quota-credits-comment.json").read_text(
+            encoding="utf-8-sig"
+        )
+    )
+    all_heads = iter(
+        [candidate.head_sha, NEXT_HEAD if head_changes else candidate.head_sha]
+    )
+
+    def read(url: str) -> object:
+        if "/reviews?" in url:
+            return [review]
+        if "/comments?" in url:
+            return [comment]
+        return {"number": candidate.pull_request, "head": {"sha": next(all_heads)}}
+
+    observed = observer.observe_codex_review(candidate, read)
+    if head_changes:
+        assert observed.reason is observer.HoldReason.HEAD_CHANGED
+        assert observed.evidence_ids == ()
+        assert observed.quota_notice_ids == ()
+    else:
+        assert observed.reason is (
+            observer.HoldReason.REVIEW_FINDINGS
+            if has_findings
+            else observer.HoldReason.NATIVE_FORMAT_UNVERIFIED
+        )
+        assert observed.evidence_ids == (review["id"],)
+        assert observed.quota_notice_ids == (5902483341,)
+
+
+def test_quota_after_stale_review_remains_diagnostic_hold() -> None:
+    comment = json.loads(
+        (Path(__file__).parent / "fixtures/codex-quota-credits-comment.json").read_text(
+            encoding="utf-8-sig"
+        )
+    )
+
+    def read(url: str) -> object:
+        if "/reviews?" in url:
+            return [{"id": 1, "commit_id": NEXT_HEAD}]
+        if "/comments?" in url:
+            return [comment]
+        return {"number": 7, "head": {"sha": HEAD}}
+
+    observed = observer.observe_codex_review(CANDIDATE, read)
+    assert observed.reason is observer.HoldReason.QUOTA_NOTICE
+    assert observed.evidence_ids == ()
+    assert observed.quota_notice_ids == (5902483341,)