claude-dev-env 8.49.4 → 8.50.1

package/docs/account-broker.md

@@ -2,7 +2,11 @@
 
 `account_broker.py` reads the Claude and Codex account rosters, checks each account's session and weekly usage, and chooses an account with room. It does not select a model or sleep. A Codex decision names the `normal` or `luna` tier for the caller.
 
-Claude's main home is `~/.claude`. Its `claude-chain.json` file contains a `chain` list; each entry's `credentials_path` field identifies the credentials file whose parent is that account's home folder. The optional `extra-profiles.json` file in the main home lists additional profile names. Codex uses its configured account roster. When no Codex roster is configured, the broker chooses the default Codex home.
+Claude's main home is `~/.claude`. Its `claude-chain.json` file contains a `chain` list; each entry's `credentials_path` field identifies the credentials file whose parent is that account's home folder. The optional `extra-profiles.json` file in the main home lists additional profile names.
+
+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.
 
 ## Commands
 

package/hooks/blocking/test_code_rules_js_conventions.py

@@ -12,7 +12,7 @@ from code_rules_js_conventions import (  # noqa: E402
     check_js_boolean_naming,
 )
 
-CONVERGE_PATH = "packages/claude-dev-env/.agents/skills/autoconverge/workflow/converge.mjs"
+CONVERGE_PATH = "skill-archive/autoconverge/workflow/converge.mjs"
 
 
 def test_flags_unprefixed_boolean_let_declaration() -> None:

package/package.json

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

package/scripts/account_broker.py

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

package/scripts/account_broker_support.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import errno
 import json
 import os
@@ -47,6 +48,8 @@ from dev_env_scripts_constants.account_broker_constants import (
     utc_time_text,
 )
 from dev_env_scripts_constants.claude_account_constants import (
+    CLAUDE_ACCOUNT_ORDER_FILE_NAME,
+    CLAUDE_LAUNCHER_PROGRAM,
     CREDENTIALS_FILE_NAME,
     EXTRA_PROFILES_FILE_NAME,
     FULL_PERCENT,
@@ -64,7 +67,7 @@ from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_EN
 
 def _read_list(path: Path) -> object:
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
+        return json.loads(path.read_text(encoding="utf-8-sig"))
     except (OSError, UnicodeError, json.JSONDecodeError) as error:
         raise BrokerConfigurationError(f"cannot read account list {path}: {error}") from error
 
@@ -121,11 +124,34 @@ def _append_claude_account(
         all_seen.add(key)
 
 
+def _account_order(main_home: Path) -> tuple[str, ...]:
+    order_path = main_home / CLAUDE_ACCOUNT_ORDER_FILE_NAME
+    if not order_path.exists():
+        return ()
+    all_names = _read_list(order_path)
+    if not isinstance(all_names, list) or any(not isinstance(each_name, str) for each_name in all_names):
+        raise BrokerConfigurationError(f"invalid account list {order_path}")
+    return tuple(each_name.casefold() for each_name in all_names)
+
+
+def _order_names(account: Account) -> frozenset[str]:
+    launcher_name = Path(CLAUDE_LAUNCHER_PROGRAM.file_name_template.format(profile_name=account.name)).stem
+    return frozenset(each_name.casefold() for each_name in (account.name, account.command, launcher_name) if each_name)
+
+
+def _with_priorities(all_accounts: Sequence[Account], all_ordered_names: Sequence[str]) -> tuple[Account, ...]:
+    def priority_of(account: Account) -> int | None:
+        all_names = _order_names(account)
+        return next((index for index, each_name in enumerate(all_ordered_names) if each_name in all_names), None)
+
+    return tuple(dataclasses.replace(each_account, priority=priority_of(each_account)) for each_account in all_accounts)
+
+
 def load_claude_accounts() -> tuple[Account, ...]:
     """Read the Claude account roster.
 
     Returns:
-        Main and additional accounts in configured order.
+        Main and additional accounts in configured order, each with its place in the account order file.
 
     Raises:
         BrokerConfigurationError: An account list is unreadable.
@@ -138,7 +164,7 @@ def load_claude_accounts() -> tuple[Account, ...]:
     for each_home in _extra_homes(main_home):
         home = each_home.resolve()
         _append_claude_account(all_accounts, all_seen, Account(Product.CLAUDE, home.name, home, command=home.name), main_home)
-    return tuple(all_accounts)
+    return _with_priorities(all_accounts, _account_order(main_home))
 
 
 def load_codex_accounts() -> tuple[Account, ...]:

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -137,6 +137,7 @@ class Account:
     home: Path
     is_main: bool = False
     command: str | None = None
+    priority: int | None = None
 
 
 @dataclass(frozen=True)
@@ -257,9 +258,10 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
     return max(all_blocking_resets, default=None)
 
 
-def _rank_key(reading: Reading) -> float:
+def _rank_key(reading: Reading) -> tuple[bool, int, float]:
     room = reading.meters.tightest_percent_left if reading.meters else None
-    return -(room if room is not None else -1.0)
+    priority = reading.account.priority
+    return (priority is None, priority or 0, -(room if room is not None else -1.0))
 
 
 def _main_has_room(meters: Meters | None) -> bool:
@@ -284,10 +286,13 @@ def _choose_claude(all_available: Sequence[Reading], preferred_command: str | No
         is_bound = preferred_command in (each_reading.account.command, each_reading.account.name)
         if preferred_command is not None and is_bound:
             return Decision("run", each_reading.account, None, "resume affinity", TIER_NORMAL)
-    roomiest = min(all_with_room, key=_rank_key, default=None)
-    if roomiest is None:
+    chosen = min(all_with_room, key=_rank_key, default=None)
+    if chosen is None:
         return None
-    return Decision("run", roomiest.account, None, f"{roomiest.account.name} has {roomiest.meters.tightest_percent_left:g}% left", TIER_NORMAL)
+    room_text = f"{chosen.account.name} has {chosen.meters.tightest_percent_left:g}% left"
+    if chosen.account.priority is not None:
+        room_text = f"{room_text}; priority {chosen.account.priority + 1} in the account order"
+    return Decision("run", chosen.account, None, room_text, TIER_NORMAL)
 
 
 def _choose_codex(all_available: Sequence[Reading]) -> Decision | None:

package/scripts/dev_env_scripts_constants/claude_account_constants.py

@@ -27,6 +27,9 @@ SECOND_ACCOUNT_PROFILE_NAME: str = "ev"
 EXTRA_PROFILES_FILE_NAME: str = "extra-profiles.json"
 """Local main-home file listing extra profile names in selection order."""
 
+CLAUDE_ACCOUNT_ORDER_FILE_NAME: str = "claude-account-order.json"
+"""Optional main-home file listing Claude accounts in pick priority, first choice first."""
+
 PROFILE_NAME_PATTERN: str = r"[A-Za-z0-9][A-Za-z0-9_-]*"
 """Allowed profile names for directories and command launchers."""
 

package/scripts/test_account_broker.py

@@ -302,6 +302,59 @@ def test_should_use_claude_extra_floors_and_wait_for_unread() -> None:
     assert decision.account is None
 
 
+def _ranked_claude_account(name: str, priority: int | None) -> Account:
+    return Account(Product.CLAUDE, name, Path("/profiles") / name, False, name, priority)
+
+
+def test_should_pick_the_first_claude_account_in_priority_order_with_room() -> None:
+    readings = (
+        Reading(_ranked_claude_account("roomy", 2), _meters(90, 90)),
+        Reading(_ranked_claude_account("spent", 0), _meters(5, 90)),
+        Reading(_ranked_claude_account("preferred", 1), _meters(20, 20)),
+        Reading(_ranked_claude_account("unranked", None), _meters(99, 99)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, readings, now=NOW)
+
+    assert decision.account.name == "preferred"
+    assert "priority 2" in decision.reason
+
+
+def test_should_fall_back_to_the_roomiest_unranked_claude_account() -> None:
+    readings = (
+        Reading(_ranked_claude_account("ranked_spent", 0), _meters(5, 5)),
+        Reading(_ranked_claude_account("tight", None), _meters(30, 30)),
+        Reading(_ranked_claude_account("roomy", None), _meters(60, 60)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, readings, now=NOW)
+
+    assert decision.account.name == "roomy"
+
+
+def test_should_keep_resume_affinity_ahead_of_priority() -> None:
+    readings = (
+        Reading(_ranked_claude_account("first", 0), _meters(90, 90)),
+        Reading(_ranked_claude_account("bound", 1), _meters(40, 40)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, readings, now=NOW, preferred_command="bound")
+
+    assert decision.account.name == "bound"
+    assert decision.reason == "resume affinity"
+
+
+def test_should_wait_when_every_ranked_claude_account_is_spent() -> None:
+    readings = (
+        Reading(_ranked_claude_account("first", 0), _meters(5, 5)),
+        Reading(_ranked_claude_account("second", 1), _meters(0, 50)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, readings, now=NOW)
+
+    assert decision.action == "wait"
+
+
 @pytest.mark.parametrize("count", (1, 5))
 def test_should_consider_every_account_in_the_roster(count: int) -> None:
     readings = tuple(

package/scripts/test_account_broker_support.py

@@ -34,6 +34,64 @@ def test_should_load_claude_roster_from_both_lists(
     assert accounts[1].home == (tmp_path / "alternate").resolve()
 
 
+def _claude_home_with_extras(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, extras: list[str]) -> Path:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setattr(support, "default_profile_home", lambda name="extra": tmp_path / "profiles" / name)
+    main_home = tmp_path / ".claude"
+    main_home.mkdir()
+    (main_home / "extra-profiles.json").write_text(json.dumps(extras), encoding="utf-8")
+    return main_home
+
+
+def test_should_leave_claude_priorities_unset_without_an_order_file(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _claude_home_with_extras(monkeypatch, tmp_path, ["first", "second"])
+
+    accounts = support.load_claude_accounts()
+
+    assert [each_account.priority for each_account in accounts] == [None, None, None]
+
+
+def test_should_assign_claude_priorities_from_the_order_file(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    main_home = _claude_home_with_extras(monkeypatch, tmp_path, ["first", "second", "unlisted"])
+    (main_home / "claude-account-order.json").write_text(
+        json.dumps(["claude-second", "missing", "claude", "FIRST"]), encoding="utf-8"
+    )
+
+    accounts = support.load_claude_accounts()
+
+    assert {each_account.name: each_account.priority for each_account in accounts} == {
+        "main": 2,
+        "first": 3,
+        "second": 0,
+        "unlisted": None,
+    }
+
+
+def test_should_read_an_order_file_saved_with_a_byte_order_mark(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    main_home = _claude_home_with_extras(monkeypatch, tmp_path, ["first"])
+    (main_home / "claude-account-order.json").write_text('["first"]', encoding="utf-8-sig")
+
+    accounts = support.load_claude_accounts()
+
+    assert {each_account.name: each_account.priority for each_account in accounts} == {"main": None, "first": 0}
+
+
+def test_should_reject_an_order_file_that_is_not_a_list_of_names(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    main_home = _claude_home_with_extras(monkeypatch, tmp_path, ["first"])
+    (main_home / "claude-account-order.json").write_text('{"order": ["first"]}', encoding="utf-8")
+
+    with pytest.raises(support.BrokerConfigurationError, match="claude-account-order.json"):
+        support.load_claude_accounts()
+
+
 def test_should_load_codex_roster_without_meter_reads(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None: