claude-dev-env 8.38.3 → 8.39.0

package/_shared/pr-loop/scripts/check_convergence.py

@@ -29,10 +29,10 @@ The frozen process env is only a fallback when that disk read fails (logged once
 A probe error does not waive the gate; the live GitHub checks still run.
 
 The Codex gate is conditional-required: it demands
-``codex_clean_at == current_head`` only when the Codex account picker
-(``scripts/codex_account_choice.py choose``) answers the ``normal`` tier, so
+``codex_clean_at == current_head`` only when the account broker
+(``scripts/account_broker.py choose --product codex``) answers the ``normal`` tier, so
 one signed-in account has room for a review. A ``luna`` or ``wait`` answer, an
-unreadable picker, the codex token, or ``codex_down`` never blocks ready.
+unreadable broker, the codex token, or ``codex_down`` never blocks ready.
 """
 
 from __future__ import annotations
@@ -64,11 +64,12 @@ from check_convergence_thread_gates import (
     _count_unresolved_bot_threads,
 )
 from pr_converge_scripts_constants.convergence_gate_constants import (
-    ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS,
+    ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS,
+    ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES,
     BUGBOT_DOWN_BYPASS_NOTE,
     CLAUDE_JOB_DIR_ENV_VAR_NAME,
     CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS,
-    CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+    CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
     CODEX_BYPASS_DETAIL,
     CODEX_CLEAN_AT_STATE_KEY,
     CODEX_CLEAN_DETAIL_TEMPLATE,
@@ -344,16 +345,16 @@ def _evaluate_codex_clean(
 
     ::
 
-        clean stamp on head                  -> pass  (picker never runs)
+        clean stamp on head                  -> pass  (broker never runs)
         no stamp, tier luna, wait, or None   -> skip  (never blocks)
         no stamp, tier normal                -> fail
 
-    A stamp on the current HEAD settles the gate on its own, so the picker
-    stays behind it: the picker starts one Codex app server per account, and
+    A stamp on the current HEAD settles the gate on its own, so the broker
+    stays behind it: the broker starts one Codex app server per account, and
     the common already-clean tick has no reason to pay for them.
 
     Args:
-        read_codex_tier: Returns the picker's tier, or None when the picker cannot say.
+        read_codex_tier: Returns the broker's tier, or None when the broker cannot say.
         codex_clean_at: HEAD SHA where Codex last reported clean, or None.
         head_sha: Current PR HEAD commit SHA.
 
@@ -367,20 +368,22 @@ def _evaluate_codex_clean(
     return False, CODEX_MISSING_CLEAN_DETAIL_TEMPLATE % _short_sha(head_sha)
 
 
-def _codex_account_picker_path() -> Path:
-    """Return the installed Codex account picker beside this shared tree."""
+def _codex_account_broker_path() -> Path:
+    """Return the installed account broker beside this shared tree."""
     shared_root = Path(__file__).resolve().parents[SHARED_PACKAGE_ROOT_PARENT_INDEX]
-    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS)
+    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS)
 
 
 def _read_codex_tier() -> str | None:
-    """Ask the Codex account picker which tier a review runs on, or None when it cannot say."""
+    """Ask the account broker which tier a review runs on, or None when it cannot say."""
     try:
         completed = subprocess.run(
             [
                 sys.executable,
-                str(_codex_account_picker_path()),
-                CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+                str(_codex_account_broker_path()),
+                CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
+                "--product",
+                "codex",
             ],
             capture_output=True,
             text=True,
@@ -390,9 +393,12 @@ def _read_codex_tier() -> str | None:
         answer = json.loads(completed.stdout)
     except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
         return None
-    if completed.returncode != 0 or not isinstance(answer, dict):
+    if completed.returncode not in ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES or not isinstance(answer, dict):
         return None
-    tier = answer.get(CODEX_TIER_KEY)
+    decision = answer.get("decision")
+    if not isinstance(decision, dict):
+        return None
+    tier = decision.get(CODEX_TIER_KEY)
     return tier if isinstance(tier, str) else None
 
 

package/_shared/pr-loop/scripts/pr_converge_scripts_constants/convergence_gate_constants.py

@@ -69,11 +69,12 @@ CODEX_CLEAN_AT_STATE_KEY: str = "codex_clean_at"
 CODEX_DOWN_STATE_KEY: str = "codex_down"
 MINIMUM_ABBREVIATED_SHA_LENGTH: int = 7
 SHARED_PACKAGE_ROOT_PARENT_INDEX: int = 3
-ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS: tuple[str, ...] = (
+ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS: tuple[str, ...] = (
     "scripts",
-    "codex_account_choice.py",
+    "account_broker.py",
 )
-CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND: str = "choose"
+CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND: str = "choose"
 CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS: float = 150.0
 CODEX_TIER_KEY: str = "tier"
+ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES: tuple[int, ...] = (0, 3)
 CODEX_TIER_NORMAL: str = "normal"

package/_shared/pr-loop/scripts/test_check_convergence_codex.py

@@ -1,7 +1,7 @@
 """Fixture-driven tests for the conditional Codex convergence gate.
 
 Covers: required-and-clean, required-and-dirty, skipped-by-tier,
-skipped-by-token, skipped-by-down, and the read of the Codex account picker's
+skipped-by-token, skipped-by-down, and the read of the account broker's
 ``choose`` answer. The required tier comes from ``CODEX_TIER_NORMAL``.
 """
 
@@ -117,15 +117,15 @@ def should_pass_when_codex_required_and_clean(
     assert "All pre-conditions met" in captured
 
 
-def should_pass_without_running_the_picker_when_the_clean_stamp_is_on_head(
+def test_should_pass_without_running_the_broker_when_the_clean_stamp_is_on_head(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    def _picker_that_must_not_run() -> str | None:
+    def _broker_that_must_not_run() -> str | None:
         raise AssertionError(
-            "the Codex account picker must not run when codex_clean_at is on HEAD"
+            "the account broker must not run when codex_clean_at is on HEAD"
         )
 
-    monkeypatch.setattr(check_convergence, "_read_codex_tier", _picker_that_must_not_run)
+    monkeypatch.setattr(check_convergence, "_read_codex_tier", _broker_that_must_not_run)
 
     is_passed, detail = check_convergence._evaluate_codex_clean(
         read_codex_tier=check_convergence._read_codex_tier,
@@ -228,7 +228,7 @@ def should_fail_when_codex_required_and_dirty(
 
 
 @pytest.mark.parametrize("tier_without_room", ALL_TIERS_WITHOUT_ROOM_FOR_REVIEW)
-def should_skip_when_the_picker_names_no_account_with_room_for_review(
+def test_should_skip_when_the_broker_names_no_account_with_room_for_review(
     tier_without_room: str, tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     fixture_path = _write_fixture(
@@ -513,47 +513,86 @@ def should_accept_codex_clean_at_flag_in_parsed_arguments() -> None:
     assert arguments.codex_clean_at == HEAD_SHA
 
 
-def _install_fake_picker(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, picker_source: str
+def _install_fake_broker(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, broker_source: str
 ) -> None:
-    picker_path = tmp_path / "codex_account_choice.py"
-    picker_path.write_text(picker_source, encoding="utf-8")
-    monkeypatch.setattr(check_convergence, "_codex_account_picker_path", lambda: picker_path)
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(broker_source, encoding="utf-8")
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
 
 
-def should_read_the_tier_the_picker_chooses(
+def test_should_read_normal_tier_from_broker_decision(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'reason': 'room'}, 'accounts': []}))\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
+
+
+def test_should_read_wait_tier_from_broker_exit_three(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'wait', 'reason': 'no room'}, 'accounts': []}))\n"
+        "sys.exit(3)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == "wait"
+
+    passed, detail = check_convergence._evaluate_codex_clean(
+        read_codex_tier=check_convergence._read_codex_tier,
+        codex_clean_at=None,
+        head_sha=HEAD_SHA,
+    )
+    assert passed
+    assert "skipped" in detail
+
+
+def test_should_read_the_tier_the_broker_chooses(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fake_broker(
         tmp_path,
         monkeypatch,
         "import json, sys\n"
-        "assert sys.argv[1:] == ['choose']\n"
-        "print(json.dumps({'tier': 'normal', 'account': 'codex-2'}))\n",
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'account': 'codex-2'}, 'accounts': []}))\n",
     )
 
     assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
 
 
 @pytest.mark.parametrize(
-    "picker_source",
+    "broker_source",
     [
-        "import sys\nprint('{\"tier\": \"normal\"}')\nsys.exit(1)\n",
+        "import sys\nprint('{\"decision\": {\"tier\": \"normal\"}}')\nsys.exit(1)\n",
         "print('not json')\n",
         "print('[\"normal\"]')\n",
-        "print('{\"tier\": 1}')\n",
+        "print('{\"decision\": {\"tier\": 1}}')\n",
     ],
 )
-def should_read_no_tier_when_the_picker_fails_or_answers_out_of_shape(
-    picker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_should_read_no_tier_when_the_broker_fails_or_answers_out_of_shape(
+    broker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(tmp_path, monkeypatch, picker_source)
+    _install_fake_broker(tmp_path, monkeypatch, broker_source)
 
     assert check_convergence._read_codex_tier() is None
 
 
-def should_locate_the_packaged_codex_account_picker() -> None:
-    picker_path = check_convergence._codex_account_picker_path()
+def test_should_locate_the_packaged_codex_account_broker() -> None:
+    broker_path = check_convergence._codex_account_broker_path()
 
-    assert picker_path.name == "codex_account_choice.py"
-    assert picker_path.is_file()
+    assert broker_path.name == "account_broker.py"
+    assert broker_path.is_file()

package/docs/codex-accounts.md

@@ -1,15 +1,16 @@
 # Codex accounts
 
-The codex_account_choice picker spreads agent work across the Codex accounts
-on one machine. Each account signs in under its own Codex home, and every home
+The account broker assigns agent work across the Codex accounts.
+Each account signs in under its own Codex home, and every home
 shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
-A job asks the picker which account to use.
+A job asks the broker which account to use.
 
 ## Pieces
 
 | File | What it does |
 |---|---|
-| `scripts/codex_account_choice.py` | `choose` names the account and tier a job runs on, `check` tells a running job whether its account is still above a floor, `sync` links the shared setup into every account's home, `setup` and `install` write one launcher per account |
+| `scripts/account_broker.py` | `choose --product codex` names the account and tier a job runs on; `check --product codex` reports whether any account has room |
+| `scripts/codex_account_choice.py` | `sync` links the shared setup into every account's home; `setup` and `install` write one launcher per account |
 | `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
 | `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
 
@@ -21,8 +22,8 @@ The account roster names the accounts and their order. It comes from the
 in `account-launchers.json` under the profiles root. When neither exists, the
 accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`.
 
-`choose`, `sync` and `check` all work on that list, in that order. `check`
-accepts only a name on it. Each account's home is `~/.codex-profiles/<name>`, or
+The broker's `choose` and `check` commands and the setup commands use that list.
+Each account's home is `~/.codex-profiles/<name>`, or
 `<name>` under `CODEX_PROFILES_ROOT` when set. `~/.codex` holds the shared setup
 and is never an account. A name uses letters, digits, hyphens or underscores.
 `main`, `wait` and the Windows device names are refused.
@@ -83,50 +84,45 @@ folder under the profiles root stays, with its `auth.json`, so typing the name
 again restores it. A blank first line empties the roster and moves every launcher
 aside.
 
-`check <name>` reads a saved name the same way:
-
-```
-python packages/claude-dev-env/scripts/codex_account_choice.py check alpha --floor 1
-```
-
 ## Which account a job uses
 
 Room is the smaller of an account's two windows: the 5-hour window and the week.
 
 | Condition | Answer |
 |---|---|
-| First account in order with more than 10% left | `normal` on that account |
-| No account over 10%, one or more over 1% | `luna` on the account with the most room, `stop_below_percent` 1 |
+| 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 |
 | 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 account whose blocking windows reset first |
-| Account not signed in, or its meter unread | skipped, with the reason in `accounts` |
+| No account over 1% | `wait`, naming the next reset when known |
+| A meter is unread | The account has `meters: null` in `accounts` |
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py choose
-{"tier": "normal", "account": "codex-1", "codex_home": "...\\codex-1", "percent_left": 62.0,
- "stop_below_percent": null, "reason": "codex-1 has 62% left", "accounts": [...]}
+python packages/claude-dev-env/scripts/account_broker.py choose --product codex
+{"decision": {"action": "run", "account": "codex-1", "home": "...\\codex-1",
+ "resets_at": null, "reason": "codex-1 has 62% left", "tier": "normal"},
+ "accounts": [{"name": "codex-1", "home": "...\\codex-1", "is_main": false,
+ "meters": {"session_percent_left": 62.0, "session_resets_at": null,
+ "weekly_percent_left": 70.0, "weekly_resets_at": null}}]}
 ```
 
-A job runs Codex with `CODEX_HOME` set to `codex_home`. On `luna`, the job runs
+A job runs Codex with `CODEX_HOME` set to `decision.home`. On `luna`, the job runs
 Luna and polls `check` between steps:
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py check codex-2 --floor 1
+python packages/claude-dev-env/scripts/account_broker.py check --product codex
 ```
 
-`check` exits 0 while the account has more than the floor left, and 3 once it has
-not or its meter is unread. The job stops on 3.
+`check` exits 3 while every account is below its floor, and 0 when an account
+has room. The job stops on 3. `choose` also exits 3 for `wait` and still prints
+the JSON answer.
 
 ## Shared callers
 
-Two scripts under `_shared` run `choose` by path. Each finds the picker at
-`scripts/codex_account_choice.py` in the directory that holds `_shared`. Once
-installed, that is `~/.claude/scripts/codex_account_choice.py`.
+Two scripts under `_shared` run `choose --product codex` by path. Each finds the
+broker at `scripts/account_broker.py` in the directory that holds `_shared`.
+Once installed, that is `~/.claude/scripts/account_broker.py`.
 
 | Caller | What it does with the answer |
 |---|---|
-| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed picker skips the Codex gate |
-| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `codex_home` |
-
-Pass `--codex-path` when `codex` is off PATH. Without it the picker also tries
-the desktop install path under the user home.
+| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed broker skips the Codex gate |
+| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `decision.home` |

package/package.json

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