claude-dev-env 8.83.2 → 8.84.0

package/docs/account-broker.md

@@ -6,7 +6,7 @@ Claude's main home is `~/.claude`. Its `claude-chain.json` file contains a `chai
 
 The optional `claude-account-order.json` file in the main home sets the Claude pick priority. It is a JSON list of account names, first choice first, such as `["claude-second", "claude"]`. An entry matches an account's name, its command, or its `claude-<name>` launcher, and `claude` names the main account. A new job goes to the first listed account with room. When no listed account has room, the broker picks the unlisted account with the most room, and it waits when no account has room. A resumed session stays on its bound account while that account has room. A listed name absent from the roster is skipped. Without the file, every job goes to the account with the most room. Edit the file to change the order; the next pick reads it.
 
-Codex uses its configured account roster. When no Codex roster is configured, the broker chooses the default Codex home.
+Codex uses its configured account roster. When no Codex roster is configured, the broker chooses the default Codex home. A new Codex job goes to an account on a Pro plan before any other account in the same tier. The plan comes from the account's meter reply, and `ALL_PRO_PLAN_TYPES` lists the Pro plans: `pro`, `prolite`, and `promax`. Among accounts of the same kind, the one with the most room wins. A Pro account below the `normal` floor still loses to any account with room in the `normal` tier.
 
 ## Commands
 

package/docs/codex-accounts.md

@@ -91,8 +91,8 @@ A window that reports no length counts as weekly.
 
 | Condition | Answer |
 |---|---|
-| One or more accounts with more than 10% left | `normal` on the account with the most room |
-| No account over 10%, one or more over 1% | `luna` on the account with the most room |
+| One or more accounts with more than 10% left | `normal` on a Pro plan account (`pro`, `prolite` and `promax`) before any other account in this tier; among accounts of the same kind, the one with the most room |
+| No account over 10%, one or more over 1% | `luna` on a Pro plan account (`pro`, `prolite` and `promax`) before any other account in this tier; among accounts of the same kind, the one with the most room |
 | An account that reports a window shorter than a week, such as the 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 read fails | The broker reads it again, up to 3 reads, waiting 1 second and then 2 seconds |

package/package.json

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

package/scripts/account_broker_support.py

@@ -315,6 +315,7 @@ def read_codex_account_meters(account: Account) -> Meters:
         short_window.resets_at if short_window else None,
         FULL_PERCENT - weekly_window.used_percent if weekly_window else None,
         weekly_window.resets_at if weekly_window else None,
+        usage.plan_type,
     )
 
 
@@ -500,6 +501,7 @@ def _meter_payload(meters: Meters | None) -> dict[str, object] | None:
         "session_resets_at": utc_time_text(meters.session_resets_at),
         "weekly_percent_left": meters.weekly_percent_left,
         "weekly_resets_at": utc_time_text(meters.weekly_resets_at),
+        "plan_type": meters.plan_type,
     }
 
 
@@ -509,7 +511,14 @@ def _meters_from_payload(raw_meters: object) -> Meters | None:
     all_percentages = (raw_meters.get("session_percent_left"), raw_meters.get("weekly_percent_left"))
     if any(each_percent is not None and not isinstance(each_percent, (int, float)) for each_percent in all_percentages):
         return None
-    return Meters(all_percentages[0], parse_utc_time(raw_meters.get("session_resets_at")), all_percentages[1], parse_utc_time(raw_meters.get("weekly_resets_at")))
+    plan_type = raw_meters.get("plan_type")
+    return Meters(
+        all_percentages[0],
+        parse_utc_time(raw_meters.get("session_resets_at")),
+        all_percentages[1],
+        parse_utc_time(raw_meters.get("weekly_resets_at")),
+        plan_type if isinstance(plan_type, str) else None,
+    )
 
 
 def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict[str, object], now: datetime) -> tuple[Reading, bool]:

package/scripts/codex_account_meters.py

@@ -4,10 +4,13 @@
 Codex reports usage through ``codex app-server`` and the JSON-RPC method
 ``account/rateLimits/read``. The reply names up to two windows, a short one
 (5 hours) and a weekly one. The account broker counts the account's room as
-the smaller of the two::
+the smaller of the two. The reply also names the account's plan, such as
+``pro`` or ``team``::
 
     5-hour window 30% used, week 85% used  -> 15% left
     week window only, 40% used             -> 60% left
+    planType "promax"                      -> plan_type "promax"
+    no planType                            -> plan_type None
     no window, error reply, no reply       -> CodexMeterUnreadError
 
 Every read failure raises ``CodexMeterUnreadError``. A missing Codex
@@ -92,9 +95,10 @@ class UsageWindow:
 
 @dataclass(frozen=True)
 class CodexAccountMeters:
-    """One account's windows, with its tightest short window and its tightest weekly window."""
+    """One account's windows and plan, with its tightest short window and its tightest weekly window."""
 
     all_windows: tuple[UsageWindow, ...]
+    plan_type: str | None = None
 
     @property
     def short_window(self) -> UsageWindow | None:
@@ -176,14 +180,16 @@ def parse_rate_limits_reply(reply_text: str) -> CodexAccountMeters:
     ::
 
         {"id": 2, "result": {"rateLimits": {"primary": {"usedPercent": 30, ...},
-                                            "secondary": {"usedPercent": 85, ...}}}}
-        -> CodexAccountMeters with two windows, 15% left
+                                            "secondary": {"usedPercent": 85, ...},
+                                            "planType": "promax"}}}
+        -> CodexAccountMeters with two windows, 15% left, plan_type "promax"
+        the same reply without "planType" -> plan_type None
 
     Args:
         reply_text: One line the ``codex app-server`` process wrote.
 
     Returns:
-        The windows the reply carries.
+        The windows and the plan type the reply carries.
 
     Raises:
         CodexMeterUnreadError: The line is no reply, an error reply, or names
@@ -197,7 +203,8 @@ def parse_rate_limits_reply(reply_text: str) -> CodexAccountMeters:
     )
     if not all_windows:
         raise CodexMeterUnreadError("rate-limit reply names no usage window")
-    return CodexAccountMeters(all_windows=all_windows)
+    plan_type = rate_limits.get("planType")
+    return CodexAccountMeters(all_windows=all_windows, plan_type=plan_type if isinstance(plan_type, str) else None)
 
 
 def request_messages() -> list[dict[str, object]]:

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -20,6 +20,7 @@ from dev_env_scripts_constants.claude_account_constants import (
     SECOND_WEEKLY_USED_CEILING_PERCENT,
 )
 from dev_env_scripts_constants.codex_account_constants import (
+    ALL_PRO_PLAN_TYPES,
     CODEX_HOME_ENVIRONMENT_VARIABLE,
     LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
     LUNA_TIER_STOP_PERCENT_LEFT,
@@ -193,6 +194,7 @@ class Meters:
     session_resets_at: datetime | None
     weekly_percent_left: float | None
     weekly_resets_at: datetime | None
+    plan_type: str | None = None
 
     @property
     def tightest_percent_left(self) -> float | None:
@@ -313,10 +315,11 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
     return max(all_known_resets, default=None)
 
 
-def _rank_key(reading: Reading) -> tuple[bool, int, float]:
+def _rank_key(reading: Reading) -> tuple[bool, int, bool, float]:
     room = reading.meters.tightest_percent_left if reading.meters else None
     priority = reading.account.priority
-    return (priority is None, priority or 0, -(room if room is not None else -1.0))
+    is_pro_plan = reading.meters is not None and reading.meters.plan_type in ALL_PRO_PLAN_TYPES
+    return (priority is None, priority or 0, not is_pro_plan, -(room if room is not None else -1.0))
 
 
 def _main_has_room(meters: Meters | None) -> bool:

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -99,6 +99,9 @@ LUNA_TIER_STOP_PERCENT_LEFT: float = 1.0
 LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT: float = 20.0
 """An account with a window shorter than a week runs Luna only with this much of it left."""
 
+ALL_PRO_PLAN_TYPES: frozenset[str] = frozenset({"pro", "prolite", "promax"})
+"""Plan types of a personal Codex Pro subscription. The broker tries these accounts first."""
+
 WEEKLY_WINDOW_MINUTES: int = 10080
 """Length of the weekly window. Any shorter window is a short window, such as 5 hours."""
 

package/scripts/dev_env_scripts_constants/test_codex_account_constants.py

@@ -86,9 +86,14 @@ def test_tier_bars_match_the_documented_table() -> None:
     normal_bar = documented_percent(constants.NORMAL_TIER_MINIMUM_PERCENT_LEFT)
     luna_stop = documented_percent(constants.LUNA_TIER_STOP_PERCENT_LEFT)
     luna_short_window_floor = documented_percent(constants.LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT)
+    pro_plans = documented_list(sorted(constants.ALL_PRO_PLAN_TYPES))
+    pro_preference = (
+        f"on a Pro plan account ({pro_plans}) before any other account in this tier; "
+        "among accounts of the same kind, the one with the most room"
+    )
     all_expected_rows = [
-        f"| One or more accounts with more than {normal_bar} left | `{constants.TIER_NORMAL}` on the account with the most room |",
-        f"| No account over {normal_bar}, one or more over {luna_stop} | `{constants.TIER_LUNA}` on the account with the most room |",
+        f"| One or more accounts with more than {normal_bar} left | `{constants.TIER_NORMAL}` {pro_preference} |",
+        f"| No account over {normal_bar}, one or more over {luna_stop} | `{constants.TIER_LUNA}` {pro_preference} |",
         f"| An account that reports a window shorter than a week, such as the 5-hour window, with under {luna_short_window_floor} of that window left | never takes `{constants.TIER_LUNA}` |",
         f"| No account over {luna_stop} | `{constants.TIER_WAIT}`, naming the next reset when known |",
     ]

package/scripts/test_account_broker.py

@@ -58,12 +58,14 @@ def _meters(
     *,
     short_reset: datetime | None = None,
     weekly_reset: datetime | None = None,
+    plan_type: str | None = None,
 ) -> Meters:
     return Meters(
         short_left,
         short_reset or NOW + timedelta(hours=5),
         weekly_left,
         weekly_reset or NOW + timedelta(days=3),
+        plan_type,
     )
 
 
@@ -125,6 +127,30 @@ def test_should_put_unread_accounts_after_readable_accounts() -> None:
     assert decision.account == readings[1].account
 
 
+def test_should_pick_a_pro_plan_account_over_a_roomier_team_account() -> None:
+    readings = (
+        Reading(_account("team-mel"), _meters(90, 85, plan_type="team")),
+        Reading(_account("personal"), _meters(40, 30, plan_type="promax")),
+    )
+
+    decision = choose_from_readings(Product.CODEX, readings, now=NOW)
+
+    assert decision.account == readings[1].account
+    assert decision.tier == "normal"
+
+
+def test_should_pick_a_team_account_in_the_normal_tier_over_a_pro_plan_account_below_the_floor() -> None:
+    readings = (
+        Reading(_account("personal"), _meters(50, 8, plan_type="pro")),
+        Reading(_account("team-jon"), _meters(40, 30, plan_type="team")),
+    )
+
+    decision = choose_from_readings(Product.CODEX, readings, now=NOW)
+
+    assert decision.account == readings[1].account
+    assert decision.tier == "normal"
+
+
 def test_should_keep_list_order_when_tighter_windows_tie() -> None:
     readings = (
         Reading(_account("first"), _meters(40, 60)),

package/scripts/test_account_broker_support.py

@@ -192,7 +192,8 @@ def test_should_read_codex_meters_through_injected_reader(
             UsageWindow(300, 20.0, short_reset),
             UsageWindow(10080, 30.0, None),
             UsageWindow(None, 50.0, unknown_length_reset),
-        )
+        ),
+        plan_type="promax",
     )
     monkeypatch.setattr(support.codex_account_meters, "resolve_codex_path", lambda _: tmp_path / "codex")
     monkeypatch.setattr(support.codex_account_meters, "read_codex_meters", lambda *_: usage)
@@ -203,6 +204,19 @@ def test_should_read_codex_meters_through_injected_reader(
     assert meters.session_resets_at == short_reset
     assert meters.weekly_percent_left == 50.0
     assert meters.weekly_resets_at == unknown_length_reset
+    assert meters.plan_type == "promax"
+
+
+def test_should_keep_the_plan_through_the_cached_meter_payload() -> None:
+    meters = Meters(80.0, None, 70.0, None, "pro")
+
+    assert support._meters_from_payload(support._meter_payload(meters)) == meters
+
+
+def test_should_load_a_cached_meter_payload_saved_without_a_plan() -> None:
+    old_payload = {"session_percent_left": 80.0, "session_resets_at": None, "weekly_percent_left": 70.0, "weekly_resets_at": None}
+
+    assert support._meters_from_payload(old_payload) == Meters(80.0, None, 70.0, None, None)
 
 
 def _codex_meter_reads(

package/scripts/test_codex_account_meters.py

@@ -65,6 +65,16 @@ class TestParseRateLimitsReply:
         )
         assert [each.used_percent for each in meters.all_windows] == [40.0]
 
+    def should_read_the_plan_type_beside_the_windows(self) -> None:
+        meters = parse_rate_limits_reply(
+            reply_line({"primary": {"usedPercent": 40}, "planType": "promax"})
+        )
+        assert meters.plan_type == "promax"
+
+    def should_read_a_reply_without_a_plan_type(self) -> None:
+        meters = parse_rate_limits_reply(reply_line({"primary": {"usedPercent": 40}}))
+        assert meters.plan_type is None
+
     def should_clamp_used_percent_past_full(self) -> None:
         meters = parse_rate_limits_reply(reply_line({"primary": {"usedPercent": 130}}))
         assert [each.used_percent for each in meters.all_windows] == [100.0]