claude-dev-env 8.68.2 → 8.68.4

package/docs/codex-accounts.md

@@ -94,7 +94,8 @@ Room is the smaller of an account's two windows: the 5-hour window and the week.
 | No account over 10%, one or more over 1% | `luna` on the account with the most room |
 | An account that reports a 5-hour window, with under 20% of that window left | never takes `luna` |
 | No account over 1% | `wait`, naming the next reset when known |
-| A meter is unread | The account has `meters: null` in `accounts` |
+| A meter read fails | The broker reads it once more |
+| A meter is unread after both reads | The account has `meters: null` and the failure text in `unread_reason`; a `wait` reason names the account and that text |
 
 ```
 python packages/claude-dev-env/scripts/account_broker.py choose --product codex

package/docs/second-claude-account.md

@@ -55,6 +55,7 @@ python packages/claude-dev-env/scripts/account_broker.py choose --product claude
 
 The JSON output has a `decision` object and an `accounts` list. Each account's
 `meters` holds its remaining percent and reset time for the 5-hour window and
-the week. An unreadable meter appears as `null`. A wait decision has
+the week. An unreadable meter appears as `null`, and the account's
+`unread_reason` holds the failure text when the reader raised one. A wait decision has
 `action: "wait"` and a `resets_at` timestamp. The broker exits with code 3 on
 wait. The worker writes the same reset time to its report.

package/hooks/features/conduct-gates.md

@@ -13,6 +13,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
 - `blocking/artifact_look_gate.py` denies an Artifact publish of an HTML page until an image was opened with Read after the page file was last written, so the agent looks at its page before it ships.
+- `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 
 ## When it fires
 
@@ -25,6 +26,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_look_gate.py` runs on `PreToolUse`, matcher `Artifact|Skill`, timeout `10` seconds in `hooks.json`. It speaks only on an `Artifact` publish of a `.html` or `.htm` file.
+- `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 
 ## Proving it
 
@@ -40,6 +42,7 @@ Preconditions:
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
+- **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 
 ## Gotchas
 

package/hooks/hooks.json

@@ -152,9 +152,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",
-            "timeout": 1800,
-            "async": true
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/artifact_dark_mode_gate.py",
+            "timeout": 60
           }
         ]
       },
@@ -278,7 +277,8 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",
-            "timeout": 1800
+            "timeout": 1800,
+            "async": true
           }
         ]
       },

package/package.json

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

package/scripts/account_broker.py

@@ -125,6 +125,7 @@ def readings_payload(all_readings: Sequence[Reading]) -> list[dict[str, object]]
             "is_main": each_reading.account.is_main,
             "priority": each_reading.account.priority,
             "meters": _meter_payload(each_reading.meters),
+            "unread_reason": each_reading.unread_reason,
         }
         for each_reading in all_readings
     ]

package/scripts/account_broker_support.py

@@ -222,20 +222,24 @@ def read_claude_meters(account: Account) -> Meters | None:
     )
 
 
-def read_codex_account_meters(account: Account) -> Meters | None:
+def read_codex_account_meters(account: Account) -> Meters:
     """Probe one Codex account.
 
     Args:
         account: Account whose meter is read.
 
     Returns:
-        Its meters, or None when the probe fails.
+        Its meters, read again once when the first read fails.
+
+    Raises:
+        CodexMeterUnreadError: Both reads failed; the message is the second failure.
+        OSError: No Codex executable was found.
     """
+    codex_path = codex_account_meters.resolve_codex_path(None)
     try:
-        codex_path = codex_account_meters.resolve_codex_path(None)
         usage = codex_account_meters.read_codex_meters(codex_path, account.home)
-    except (codex_account_meters.CodexMeterUnreadError, OSError):
-        return None
+    except codex_account_meters.CodexMeterUnreadError:
+        usage = codex_account_meters.read_codex_meters(codex_path, account.home)
     weekly = [window for window in usage.all_windows if window.duration_minutes is None or window.duration_minutes >= WEEKLY_WINDOW_MINUTES]
     short = [window for window in usage.all_windows if window.duration_minutes is not None and window.duration_minutes < WEEKLY_WINDOW_MINUTES]
     weekly_window = max(weekly, key=lambda window: window.used_percent) if weekly else None
@@ -401,13 +405,16 @@ def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict
     key = _state_key(account)
     cached = all_cache.get(key)
     if isinstance(cached, dict) and isinstance(cached.get("read_at"), (int, float)) and 0 <= now.timestamp() - cached["read_at"] < 60:
-        return Reading(account, _meters_from_payload(cached.get("meters"))), False
+        cached_reason = cached.get("unread_reason")
+        return Reading(account, _meters_from_payload(cached.get("meters")), cached_reason if isinstance(cached_reason, str) else None), False
+    unread_reason = None
     try:
         meters = adapter.read_meters(account)
-    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError):
+    except (codex_account_meters.CodexMeterUnreadError, OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
         meters = None
-    all_cache[key] = {"read_at": now.timestamp(), "meters": _meter_payload(meters)}
-    return Reading(account, meters), True
+        unread_reason = str(error) or type(error).__name__
+    all_cache[key] = {"read_at": now.timestamp(), "meters": _meter_payload(meters), "unread_reason": unread_reason}
+    return Reading(account, meters, unread_reason), True
 
 
 def read_accounts(product: Product, adapter: ProductAdapter | None = None, *, all_state: dict[str, object] | None = None, now: datetime | None = None) -> tuple[Reading, ...]:

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -158,6 +158,7 @@ class Meters:
 class Reading:
     account: Account
     meters: Meters | None
+    unread_reason: str | None = None
 
 
 @dataclass(frozen=True)
@@ -318,6 +319,12 @@ class _RetryTime:
     is_known_reset: bool
 
 
+def _unreadable_text(reading: Reading) -> str:
+    if reading.unread_reason is None:
+        return reading.account.name
+    return f"{reading.account.name} ({reading.unread_reason})"
+
+
 def _wait_reason(all_unreadable_names: Sequence[str], is_every_account_unreadable: bool, soonest: _RetryTime) -> str:
     next_event = "reset" if soonest.is_known_reset else "check"
     next_text = f"next {next_event} at {utc_time_text(soonest.at)}"
@@ -341,7 +348,7 @@ def _wait_decision(
         all_retry_times.append(_RetryTime(reset, is_known_reset=True) if reset is not None and reset > now else next_check)
     soonest = min(all_retry_times, key=lambda each_retry_time: each_retry_time.at, default=next_check)
     all_unreadable_names = [
-        each_reading.account.name
+        _unreadable_text(each_reading)
         for each_reading in all_readings
         if each_reading.meters is None and each_reading.account not in all_spent_accounts
     ]

package/scripts/test_account_broker.py

@@ -75,6 +75,31 @@ def _adapter(accounts: tuple[Account, ...], meters: dict[str, Meters | None]) ->
     )
 
 
+def test_should_name_the_unread_account_and_its_reason_when_no_account_has_room() -> None:
+    codex_3 = _account("codex-3")
+    codex_4 = _account("codex-4")
+
+    def read_meter(account: Account) -> Meters:
+        if account is codex_3:
+            raise OSError("codex app-server failed: timed out")
+        return _meters(0, 40, short_reset=NOW + timedelta(hours=2))
+
+    adapter = ProductAdapter(lambda: (codex_3, codex_4), read_meter, "CODEX_HOME", ())
+    state = account_broker._load_state(account_broker.broker_state_path())
+    readings = account_broker.read_accounts(Product.CODEX, adapter, all_state=state, now=NOW)
+
+    decision = choose_from_readings(Product.CODEX, readings, now=NOW)
+    payload = account_broker.readings_payload(readings)
+
+    assert decision.action == "wait"
+    assert decision.reason == (
+        "no readable account has room; meter unreadable for codex-3 (codex app-server failed: timed out); "
+        "next check at 2026-10-03T01:00:00+00:00"
+    )
+    assert payload[0]["unread_reason"] == "codex app-server failed: timed out"
+    assert payload[1]["unread_reason"] is None
+
+
 def test_should_rank_by_room_in_the_tighter_window() -> None:
     readings = (
         Reading(_account("first"), _meters(12, 80)),

package/scripts/test_account_broker_support.py

@@ -137,6 +137,59 @@ def test_should_read_codex_meters_through_injected_reader(
     assert meters.weekly_percent_left == 70.0
 
 
+def _codex_meter_reads(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, all_outcomes: list[object]
+) -> list[Path]:
+    all_homes_read: list[Path] = []
+
+    def read_codex_meters(_codex_path: Path, codex_home: Path) -> object:
+        all_homes_read.append(codex_home)
+        outcome = all_outcomes.pop(0)
+        if isinstance(outcome, Exception):
+            raise outcome
+        return outcome
+
+    monkeypatch.setattr(support.codex_account_meters, "resolve_codex_path", lambda _: tmp_path / "codex")
+    monkeypatch.setattr(support.codex_account_meters, "read_codex_meters", read_codex_meters)
+    return all_homes_read
+
+
+def test_should_read_codex_meters_again_after_one_failed_read(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    weekly = SimpleNamespace(duration_minutes=10080, used_percent=30.0, resets_at=None)
+    usage = SimpleNamespace(all_windows=(weekly,), short_window_percent_left=None)
+    unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server sent no rate-limit reply")
+    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [unread, usage])
+
+    meters = support.read_codex_account_meters(Account(Product.CODEX, "one", tmp_path))
+
+    assert meters is not None
+    assert meters.weekly_percent_left == 70.0
+    assert all_homes_read == [tmp_path, tmp_path]
+
+
+def test_should_keep_the_unread_reason_after_two_failed_codex_reads(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(support, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
+    first_unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server failed: timed out")
+    second_unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server sent no rate-limit reply")
+    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [first_unread, second_unread])
+    account = Account(Product.CODEX, "codex-3", tmp_path)
+    adapter = ProductAdapter(lambda: (account,), support.read_codex_account_meters, "CODEX_HOME", ())
+    state = support._load_state(support.broker_state_path())
+    now = datetime(2026, 10, 3, tzinfo=timezone.utc)
+
+    first_reading = support.read_accounts(Product.CODEX, adapter, all_state=state, now=now)[0]
+    cached_reading = support.read_accounts(Product.CODEX, adapter, all_state=state, now=now)[0]
+
+    assert first_reading.meters is None
+    assert first_reading.unread_reason == "codex app-server sent no rate-limit reply"
+    assert cached_reading.unread_reason == "codex app-server sent no rate-limit reply"
+    assert all_homes_read == [tmp_path, tmp_path]
+
+
 def test_should_cache_account_reading_under_injected_state_path(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None: