claude-dev-env 8.68.3 → 8.69.0

package/.agents/skills/correction/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: correction
-description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake. Use when the user types /correction followed by what the agent got wrong.
-argument-hint: "<what the agent got wrong, in the user's words>"
+description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake, or land the fix in this session with the fix playbook. Use when the user types /correction followed by what the agent got wrong, or /correction fix to land the fix here.
+argument-hint: "[fix] <what the agent got wrong, in the user's words>"
 ---
 
 # /correction
 
-The user corrected an agent and wants the fix to stick. Write one brief they can paste into the place that turns corrections into lasting fixes.
+The user corrected an agent and wants the fix to stick. Write one brief that records the correction. By default the user pastes it into the place that turns corrections into lasting fixes. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself.
 
-`$ARGUMENTS` is the user's statement of the correction. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
+`$ARGUMENTS` is the user's statement of the correction, after a leading `fix` when one is present. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
 
-Print the brief as one fenced `text` block, and nothing after it:
+Print the brief as one fenced `text` block:
 
 ```text
-Correction: <$ARGUMENTS, word for word>
+Correction: <$ARGUMENTS word for word, minus a leading fix>
 Asked: <what the user asked for, quoted where a message carries it>
 Agent did: <what the agent did, with the reply, file, or command that shows it>
 Corrected to: <what the user wanted instead, or the fix already made>
@@ -22,4 +22,18 @@ Evidence: <file:line, log line, or quoted message that shows the miss>
 Repeat: <yes, with the earlier time it happened | no | unknown>
 ```
 
-Keep each field to one or two lines. Leave out the layer and the fix design; the intake decides those.
+Keep each field to one or two lines. Leave out the layer and the fix design; the intake or the fix playbook decides those.
+
+## Playbooks
+
+| Mode | What follows the brief |
+|---|---|
+| Hand off, the default | Nothing. The brief is the whole reply. |
+| `fix` | Read [`playbooks/fix.md`](playbooks/fix.md) right after the brief, and run its steps from step 2. |
+
+## Layout
+
+| File | What it holds |
+|---|---|
+| `SKILL.md` | The brief and the playbook index |
+| `playbooks/fix.md` | The steps that land one correction as a control and a pull request in this session |

package/.agents/skills/correction/playbooks/fix.md

@@ -0,0 +1,14 @@
+# Fix
+
+Use this playbook when this session lands the fix for the correction itself. One correction gets one control and one pull request.
+
+1. Write the brief from [`../SKILL.md`](../SKILL.md) first. It is the record every later step reads.
+2. When pstack is loaded, invoke `/pstack:poteto-mode`, then `/correct`. Point `/correct` at the brief's mistake alone, and skip its sweep of the whole repository.
+3. Read the correction instructions of the repository the mistake happened in. Open each `AGENTS.md` or `CLAUDE.md` index line that names corrections, and any intake note it points to. Where they name the target repository, the proof, or the run route, they win over this playbook.
+4. Search for an existing control: a rule, hook, lint, test, or skill that already names this mistake. A control that exists and still let the mistake through makes this a repeat.
+5. Choose the layer with [`correction-lens.md`](../../../../docs/rule-guides/correction-lens.md). When `Repeat` is `yes`, or step 4 found a control, go one layer above the one that failed.
+6. Land the control in the repository whose code, CI, or agents it guards, per the guide's "Where the control lands" section. When that repository is not in this session, add it. When it cannot be added, print the brief, name the missing repository, and stop.
+7. Prove the control. Show it fail on the mistake from the brief's `Evidence` line, then pass with the change, per [`falsify-before-green.md`](../../../../rules/falsify-before-green.md) and [`proof-before-pull-request.md`](../../../../rules/proof-before-pull-request.md). Without that proof, open no pull request.
+8. Open the pull request through `pr-lifecycle`. Put the brief, the layer, and both proof results in the body.
+
+**Reply:** the layer chosen, why each higher layer cannot hold the lesson, and the pull request link.

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.68.3",
+    "version": "8.69.0",
     "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: