claude-dev-env 8.98.10 → 8.98.11

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 list. 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.
+Codex uses its configured account list. A broker run that reads `CODEX_ACCOUNT_PROFILES` saves that list to `account-launchers.json`, so a later run without the variable reads the same roster; [Codex accounts](codex-accounts.md) has the details. 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

@@ -22,6 +22,11 @@ The account list 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`.
 
+Each read of the variable's list saves it to `account-launchers.json` when the
+file holds a different list. A service, runner, or other process started
+without the variable then reads the same roster from the file. When the file
+cannot be written, the read prints a warning and uses the variable's list.
+
 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
@@ -84,6 +89,12 @@ 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.
 
+While `CODEX_ACCOUNT_PROFILES` is set, the variable's list stays the roster. The
+next broker, sync, or install run saves it over the setup list, and setup prints
+a warning when the two differ. Change or clear the variable to change the
+roster. Two processes with different values of the variable each save their own
+list, so a process without the variable reads whichever list was saved last.
+
 ## Which account a job uses
 
 Room is the least percent left across an account's windows, such as the 5-hour window and the week.

package/package.json

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

package/scripts/codex_account_choice.py

@@ -5,7 +5,9 @@ Each Codex account signs in under its own Codex home in
 ``~/.codex-profiles/<name>``. The account list names them in try order: the
 ``CODEX_ACCOUNT_PROFILES`` environment variable, comma-separated, else the saved
 ``account-launchers.json`` list under the profiles root. With neither,
-``codex-1`` through ``codex-4`` are the roster.
+``codex-1`` through ``codex-4`` are the roster. An environment roster that
+differs from the saved file is saved to it, so a process without the variable
+reads the same roster.
 
 Three commands::
 
@@ -27,6 +29,7 @@ import argparse
 import json
 import os
 import sys
+import time
 from collections.abc import Callable, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
@@ -60,8 +63,12 @@ from dev_env_scripts_constants.codex_account_constants import (
     MAIN_CODEX_HOME_DIRECTORY_NAME,
     ROSTER_JSON_INDENT,
     ROSTER_NOT_A_LIST_TEMPLATE,
+    ROSTER_REPLACE_ATTEMPTS,
+    ROSTER_REPLACE_RETRY_SECONDS,
+    SAVE_ENVIRONMENT_ROSTER_FAILED_TEMPLATE,
     SETUP_NAMES_SEPARATOR,
     SETUP_NO_SAVED_NAMES_TEXT,
+    SETUP_OVERRIDDEN_BY_ENVIRONMENT_TEMPLATE,
     SETUP_PROMPT_TEXT,
     SETUP_SAVED_NAMES_TEMPLATE,
     TEXT_ENCODING,
@@ -156,12 +163,44 @@ def _saved_roster_file_names(profiles_root: Path) -> tuple[str, ...]:
     return _roster(document, str(roster_path))
 
 
+def _saved_roster_or_nothing(profiles_root: Path) -> tuple[str, ...]:
+    try:
+        return _saved_roster_file_names(profiles_root)
+    except (CodexAccountNameError, OSError, UnicodeError):
+        return ()
+
+
+def _save_environment_roster(
+    profiles_root: Path, all_environment_names: tuple[str, ...]
+) -> None:
+    """Copy the environment roster into the saved file when the two differ.
+
+    A process started without ``CODEX_ACCOUNT_PROFILES`` then reads the same
+    roster from the file.
+
+    Args:
+        profiles_root: The directory that holds every account's Codex home.
+        all_environment_names: The validated names the environment gives.
+    """
+    if _saved_roster_or_nothing(profiles_root) == all_environment_names:
+        return
+    try:
+        save_codex_account_names(profiles_root, all_environment_names)
+    except OSError as error:
+        print(
+            SAVE_ENVIRONMENT_ROSTER_FAILED_TEMPLATE.format(
+                path=profiles_root / CODEX_ACCOUNT_LAUNCHERS_FILE_NAME, error=error
+            ),
+            file=sys.stderr,
+        )
+
+
 def saved_codex_account_names(profiles_root: Path) -> tuple[str, ...]:
     """Name the account list, in try order, without duplicates.
 
     ::
 
-        CODEX_ACCOUNT_PROFILES="alpha, beta,alpha" -> ("alpha", "beta")
+        CODEX_ACCOUNT_PROFILES="alpha, beta,alpha" -> ("alpha", "beta"), saved to the file
         unset, account-launchers.json ["gamma"]    -> ("gamma",)
         unset, no file                             -> ()
 
@@ -170,11 +209,16 @@ def saved_codex_account_names(profiles_root: Path) -> tuple[str, ...]:
 
     Returns:
         The environment's names when it names any, else the saved file's names.
+        Environment names that differ from the file are saved to it.
 
     Raises:
         CodexAccountNameError: When the environment or the file names an invalid account.
     """
-    return _environment_roster() or _saved_roster_file_names(profiles_root)
+    all_environment_names = _environment_roster()
+    if all_environment_names:
+        _save_environment_roster(profiles_root, all_environment_names)
+        return all_environment_names
+    return _saved_roster_file_names(profiles_root)
 
 
 def codex_account_names(profiles_root: Path) -> tuple[str, ...]:
@@ -192,15 +236,48 @@ def codex_account_names(profiles_root: Path) -> tuple[str, ...]:
 def save_codex_account_names(profiles_root: Path, all_names: Sequence[str]) -> None:
     """Write the account list as a JSON list under the profiles root.
 
+    The list goes to a staged file first, and ``os.replace`` moves it over the
+    saved file in one step, so a concurrent reader sees the old list or the new one.
+
     Args:
         profiles_root: The directory that holds every account's Codex home.
         all_names: The account names in try order.
     """
     profiles_root.mkdir(parents=True, exist_ok=True)
     roster_text = json.dumps(list(all_names), indent=ROSTER_JSON_INDENT) + "\n"
-    (profiles_root / CODEX_ACCOUNT_LAUNCHERS_FILE_NAME).write_bytes(
-        roster_text.encode(TEXT_ENCODING)
-    )
+    roster_path = profiles_root / CODEX_ACCOUNT_LAUNCHERS_FILE_NAME
+    staged_path = roster_path.with_name(f"{roster_path.name}.{os.getpid()}.tmp")
+    try:
+        staged_path.write_bytes(roster_text.encode(TEXT_ENCODING))
+        _replace_with_retries(staged_path, roster_path)
+    except OSError:
+        staged_path.unlink(missing_ok=True)
+        raise
+
+
+def _replace_with_retries(staged_path: Path, roster_path: Path) -> None:
+    """Replace the saved roster, retrying while a Windows reader holds it open.
+
+    Args:
+        staged_path: The fully written new roster file.
+        roster_path: The saved roster file to replace.
+
+    Raises:
+        PermissionError: When the saved file stays locked through every attempt.
+    """
+    for _ in range(ROSTER_REPLACE_ATTEMPTS - 1):
+        if _replaced(staged_path, roster_path):
+            return
+        time.sleep(ROSTER_REPLACE_RETRY_SECONDS)
+    os.replace(staged_path, roster_path)
+
+
+def _replaced(staged_path: Path, roster_path: Path) -> bool:
+    try:
+        os.replace(staged_path, roster_path)
+    except PermissionError:
+        return False
+    return True
 
 
 def _sync_account(
@@ -403,9 +480,24 @@ def _run_setup(arguments: argparse.Namespace) -> int:
         now=now,
     )
     print(json.dumps({JSON_INSTALLED_KEY: all_installed, JSON_RETIRED_KEY: all_retired}))
+    _warn_when_the_environment_replaces(all_names)
     return 0
 
 
+def _warn_when_the_environment_replaces(all_setup_names: tuple[str, ...]) -> None:
+    try:
+        all_environment_names = _environment_roster()
+    except CodexAccountNameError:
+        return
+    if all_environment_names and all_environment_names != all_setup_names:
+        print(
+            SETUP_OVERRIDDEN_BY_ENVIRONMENT_TEMPLATE.format(
+                names=SETUP_NAMES_SEPARATOR.join(all_environment_names)
+            ),
+            file=sys.stderr,
+        )
+
+
 def _add_main_home_argument(command_parser: argparse.ArgumentParser) -> None:
     command_parser.add_argument(
         "--main-home", type=Path, default=Path.home() / MAIN_CODEX_HOME_DIRECTORY_NAME

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -39,6 +39,23 @@ INVALID_ACCOUNT_ROSTER_TEMPLATE: str = "{source} names {name!r}: {reason}"
 ROSTER_NOT_A_LIST_TEMPLATE: str = "{source} must hold a JSON list of account names"
 """Error when the roster JSON is anything other than a list of names."""
 
+SAVE_ENVIRONMENT_ROSTER_FAILED_TEMPLATE: str = (
+    "warning: cannot save the CODEX_ACCOUNT_PROFILES roster to {path}: {error}"
+)
+"""Warning when the environment roster cannot be copied into the saved file."""
+
+ROSTER_REPLACE_ATTEMPTS: int = 5
+"""Tries at replacing the saved roster while a Windows reader holds it open."""
+
+ROSTER_REPLACE_RETRY_SECONDS: float = 0.05
+"""Pause between tries at replacing the saved roster."""
+
+SETUP_OVERRIDDEN_BY_ENVIRONMENT_TEMPLATE: str = (
+    "warning: CODEX_ACCOUNT_PROFILES names {names}; the next broker, sync or install run"
+    " saves that list over this setup list"
+)
+"""Warning when setup saves a list that the environment roster will replace."""
+
 ROSTER_JSON_INDENT: int = 2
 """Indent of the saved roster JSON, one name per line."""
 

package/scripts/test_account_broker.py

@@ -850,6 +850,18 @@ def test_should_use_default_codex_home_without_roster(
     assert "no roster" in decision.reason
 
 
+def test_should_keep_the_codex_roster_for_a_process_without_the_roster_variable(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(account_broker.support.codex_account_choice, "default_profiles_root", lambda: tmp_path / "profiles")
+    monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "team,personal")
+    assert [each_account.name for each_account in account_broker.load_codex_accounts()] == ["team", "personal"]
+
+    monkeypatch.delenv("CODEX_ACCOUNT_PROFILES")
+
+    assert [each_account.name for each_account in account_broker.load_codex_accounts()] == ["team", "personal"]
+
+
 def test_should_reuse_meter_cache_for_60_seconds() -> None:
     account = _account("cached")
     calls: list[str] = []

package/scripts/test_codex_account_choice.py

@@ -144,6 +144,79 @@ class TestAccountRoster:
         monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", " beta , alpha,, ")
         assert choice.saved_codex_account_names(tmp_path) == ("beta", "alpha")
 
+    def should_save_the_environment_roster_for_a_process_without_it(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "beta,alpha")
+        assert choice.saved_codex_account_names(tmp_path) == ("beta", "alpha")
+        monkeypatch.delenv("CODEX_ACCOUNT_PROFILES")
+        assert choice.saved_codex_account_names(tmp_path) == ("beta", "alpha")
+
+    @pytest.mark.parametrize("saved_bytes", [b'["alpha",', b"\xff\xfe\x00"])
+    def should_replace_an_unreadable_saved_file_with_the_environment_roster(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, saved_bytes: bytes
+    ) -> None:
+        (tmp_path / "account-launchers.json").write_bytes(saved_bytes)
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha")
+        assert choice.saved_codex_account_names(tmp_path) == ("alpha",)
+        assert json.loads((tmp_path / "account-launchers.json").read_text(encoding="utf-8")) == ["alpha"]
+
+    def should_keep_the_environment_roster_when_the_saved_file_cannot_be_read(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        def refuse_read(_: Path) -> tuple[str, ...]:
+            raise PermissionError("locked")
+
+        monkeypatch.setattr(choice, "_saved_roster_file_names", refuse_read)
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha")
+        assert choice.saved_codex_account_names(tmp_path) == ("alpha",)
+
+    def should_remove_the_staged_roster_when_the_write_fails(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        original_write_bytes = Path.write_bytes
+
+        def fail_after_partial_write(path: Path, data: bytes) -> int:
+            original_write_bytes(path, data[:3])
+            raise OSError("disk full")
+
+        monkeypatch.setattr(Path, "write_bytes", fail_after_partial_write)
+        with pytest.raises(OSError, match="disk full"):
+            choice.save_codex_account_names(tmp_path, ("alpha",))
+        assert list(tmp_path.iterdir()) == []
+
+    @pytest.mark.parametrize("document", [["gamma"], ["alpha", "bad name"], {"alpha": 1}])
+    def should_replace_a_saved_file_that_differs_from_the_environment(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, document: object
+    ) -> None:
+        save_roster(tmp_path, document)
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha")
+        choice.saved_codex_account_names(tmp_path)
+        assert json.loads((tmp_path / "account-launchers.json").read_text(encoding="utf-8")) == ["alpha"]
+
+    def should_leave_a_saved_file_that_matches_the_environment_untouched(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        save_roster(tmp_path, ["beta", "alpha"])
+        saved_bytes = (tmp_path / "account-launchers.json").read_bytes()
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "beta,alpha")
+        choice.saved_codex_account_names(tmp_path)
+        assert (tmp_path / "account-launchers.json").read_bytes() == saved_bytes
+
+    def should_keep_the_environment_roster_when_the_file_cannot_be_written(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        def refuse_save(*_: object) -> None:
+            raise PermissionError("read-only")
+
+        monkeypatch.setattr(choice, "save_codex_account_names", refuse_save)
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha")
+        assert choice.saved_codex_account_names(tmp_path) == ("alpha",)
+        assert "cannot save the CODEX_ACCOUNT_PROFILES roster" in capsys.readouterr().err
+
     def should_read_the_saved_file_when_the_environment_is_unset(
         self, tmp_path: Path
     ) -> None:
@@ -190,6 +263,37 @@ class TestAccountRoster:
             b'[\n  "alpha",\n  "beta"\n]\n'
         )
         assert choice.saved_codex_account_names(profiles_root) == ("alpha", "beta")
+        assert [each.name for each in profiles_root.iterdir()] == ["account-launchers.json"]
+
+    def should_retry_a_replace_while_a_reader_holds_the_roster(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        original_replace = os.replace
+        all_attempts: list[object] = []
+
+        def refuse_first_replace(source: Path, target: Path) -> None:
+            all_attempts.append(source)
+            if len(all_attempts) == 1:
+                raise PermissionError("in use")
+            original_replace(source, target)
+
+        monkeypatch.setattr(choice.os, "replace", refuse_first_replace)
+        monkeypatch.setattr(choice.time, "sleep", lambda _: None)
+        choice.save_codex_account_names(tmp_path, ("alpha",))
+        assert len(all_attempts) == 2
+        assert json.loads((tmp_path / "account-launchers.json").read_text(encoding="utf-8")) == ["alpha"]
+
+    def should_remove_the_staged_roster_when_the_replace_fails(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        def refuse_replace(*_: object) -> None:
+            raise PermissionError("in use")
+
+        monkeypatch.setattr(choice.os, "replace", refuse_replace)
+        monkeypatch.setattr(choice.time, "sleep", lambda _: None)
+        with pytest.raises(PermissionError):
+            choice.save_codex_account_names(tmp_path, ("alpha",))
+        assert list(tmp_path.iterdir()) == []
 
     def should_fall_back_to_the_four_fixed_accounts_without_a_roster(
         self, tmp_path: Path
@@ -308,6 +412,23 @@ class TestSetupRoster:
             "profile name must use letters, digits, hyphens, or underscores",
         ]
 
+    @pytest.mark.parametrize(("environment_roster", "is_warned"), [("alpha,beta", True), ("alpha", False), ("", False), ("bad name", False)])
+    def should_warn_when_the_environment_roster_will_replace_the_setup_list(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+        environment_roster: str,
+        is_warned: bool,
+    ) -> None:
+        monkeypatch.setattr(choice, "update_codex_account_roster", lambda **_: (("alpha",), {}))
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", environment_roster)
+        all_arguments = ["--profiles-root", str(tmp_path / "profiles"), "setup"]
+        main_home = build_codex_main_home(tmp_path)
+        assert choice.main([*all_arguments, "--main-home", str(main_home), "--launcher-directory", str(tmp_path / "bin")]) == 0
+        assert ("CODEX_ACCOUNT_PROFILES names alpha" in capsys.readouterr().err) is is_warned
+        assert (tmp_path / "bin" / "codex-alpha.cmd").is_file()
+
     def should_finish_at_the_end_of_input(self, tmp_path: Path) -> None:
         all_names, _ = choice.update_codex_account_roster(
             profiles_root=tmp_path,