claude-dev-env 8.34.0 → 8.35.0

package/docs/codex-accounts.md

@@ -1,24 +1,31 @@
 # Codex accounts
 
-The codex_account_choice picker spreads agent work across up to four Codex
-accounts on one machine. Each account signs in under
-its own Codex home, and every home shares the same Codex setup: config, rules,
-skills, plugins and prompts. A job asks the picker which account to use.
+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
+shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
+A job asks the picker 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 |
+| `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/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 account names in try order, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
+| `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 |
 
 ## Names and order
 
-The accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`. Their homes are
-`~/.codex-profiles/codex-1` and so on, or under `CODEX_PROFILES_ROOT` when set.
-Jobs try them in that order. The names say nothing about a plan, so a plan change
-keeps every name. To change the order, sign the accounts into different folders.
+The account roster names the accounts and their order. It comes from the
+`CODEX_ACCOUNT_PROFILES` environment variable, a comma-separated list such as
+`alpha,beta`. When that variable is unset or empty, the roster is the saved list
+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
+`<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.
 
 ## Sign in once
 
@@ -33,8 +40,54 @@ $env:CODEX_HOME = "$HOME\.codex-profiles\codex-1"; codex login
 ```
 
 The sign-in lives in that folder's `auth.json`. Only the entries in
-`ALL_SHARED_CODEX_HOME_NAMES` link to `~/.codex`. Sign-in, sessions, history,
-logs and state files stay per account.
+`ALL_SHARED_CODEX_HOME_NAMES` link to `~/.codex`. They are `AGENTS.md`, `agents`,
+`config.toml`, `hooks`, `hooks.json`, `plugins`, `prompts`, `rules` and `skills`.
+Sign-in, sessions, history, logs and state files stay per account.
+
+## Named launchers
+
+Each roster account gets a launcher, `codex-<name>.cmd`, in `~/.local/bin`. It
+sets `CODEX_HOME` to that account's home and runs Codex with every argument, so
+`codex-alpha exec "fix the test"` runs on the `alpha` account.
+
+Run the setup once:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py setup
+```
+
+It prints the saved names, then asks for one name per line. A blank line or the
+end of input finishes. An invalid name prints the reason and asks again. A
+repeated name counts once. The setup saves the list to
+`~/.codex-profiles/account-launchers.json`, links each account's home to
+`~/.codex`, and writes each launcher.
+
+Rerun the installer after the shared setup or this package changes:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py install
+```
+
+It reads the roster, links every account's home, and rewrites any launcher that
+differs. A second run changes nothing. With no roster it prints `{}`.
+`CODEX_ACCOUNT_PROFILES` overrides the saved file here too. Both commands take
+`--main-home` and `--launcher-directory`.
+
+The launcher runs `call codex %*`. `codex` is npm's `codex.cmd`, and its last
+line ends the batch scope. Without `call`, that line also drops the launcher's
+`CODEX_HOME`, and Codex runs on the main home.
+
+The names typed in one setup run become the whole roster. A saved name
+left out has its launcher renamed to `codex-<name>.cmd.replaced-<time>`. Its
+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
 

package/package.json

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

package/scripts/claude_account_profile.py

@@ -309,8 +309,60 @@ def sync_profile(
     )
 
 
-def _moved_launcher_name(launcher_file_name: str, now: datetime) -> str:
-    return f"{launcher_file_name}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+def sync_report_payload(report: ProfileSyncReport) -> dict[str, object]:
+    """Turn a sync report into its JSON payload.
+
+    Args:
+        report: The entries one sync linked, moved aside, and unlinked.
+
+    Returns:
+        The linked, moved-aside, and unlinked entries as JSON lists.
+    """
+    return {
+        JSON_LINKED_KEY: list(report.all_linked),
+        JSON_MOVED_ASIDE_KEY: list(report.all_moved_aside),
+        JSON_UNLINKED_KEY: list(report.all_unlinked),
+    }
+
+
+def move_launcher_aside(launcher_path: Path, now: datetime) -> Path:
+    """Rename a launcher to ``<name>.replaced-<time>`` beside it.
+
+    Args:
+        launcher_path: The launcher to move.
+        now: The run time that names the moved launcher.
+
+    Returns:
+        The moved launcher's path.
+    """
+    moved_path = launcher_path.with_name(
+        f"{launcher_path.name}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+    )
+    os.replace(launcher_path, moved_path)
+    return moved_path
+
+
+def launcher_path(
+    launcher_directory: Path,
+    profile_name: str,
+    launcher_file_name_template: str = LAUNCHER_FILE_NAME_TEMPLATE,
+) -> Path:
+    """Name the launcher file for a profile.
+
+    Args:
+        launcher_directory: The directory on PATH that holds the launcher.
+        profile_name: The name used in the launcher file name.
+        launcher_file_name_template: The launcher file name, with ``{profile_name}``.
+
+    Returns:
+        The launcher path.
+
+    Raises:
+        ValueError: When the profile name is not a valid profile name.
+    """
+    return launcher_directory / launcher_file_name_template.format(
+        profile_name=validate_profile_name(profile_name)
+    )
 
 
 def write_launcher(
@@ -319,6 +371,8 @@ def write_launcher(
     profile_home: Path,
     now: datetime,
     profile_name: str = SECOND_ACCOUNT_PROFILE_NAME,
+    launcher_file_name_template: str = LAUNCHER_FILE_NAME_TEMPLATE,
+    launcher_text_template: str = LAUNCHER_TEXT_TEMPLATE,
 ) -> Path:
     """Write the launcher that runs Claude under a named profile.
 
@@ -333,26 +387,24 @@ def write_launcher(
         profile_home: The named account's Claude home.
         now: The run time that names a moved older launcher.
         profile_name: The name used in the launcher file name.
+        launcher_file_name_template: The launcher file name, with ``{profile_name}``.
+        launcher_text_template: The launcher body, with ``{profile_home}``.
 
     Returns:
         The launcher path.
     """
-    launcher_file_name = LAUNCHER_FILE_NAME_TEMPLATE.format(
-        profile_name=validate_profile_name(profile_name)
+    target_path = launcher_path(
+        launcher_directory, profile_name, launcher_file_name_template
     )
-    launcher_path = launcher_directory / launcher_file_name
-    launcher_text = LAUNCHER_TEXT_TEMPLATE.format(profile_home=profile_home)
+    launcher_text = launcher_text_template.format(profile_home=profile_home)
     launcher_bytes = launcher_text.encode(TEXT_ENCODING)
-    if launcher_path.is_file() and launcher_path.read_bytes() == launcher_bytes:
-        return launcher_path
-    if launcher_path.is_file():
-        os.replace(
-            launcher_path,
-            launcher_path.with_name(_moved_launcher_name(launcher_file_name, now)),
-        )
+    if target_path.is_file() and target_path.read_bytes() == launcher_bytes:
+        return target_path
+    if target_path.is_file():
+        move_launcher_aside(target_path, now)
     launcher_directory.mkdir(parents=True, exist_ok=True)
-    launcher_path.write_bytes(launcher_bytes)
-    return launcher_path
+    target_path.write_bytes(launcher_bytes)
+    return target_path
 
 
 def _build_argument_parser() -> argparse.ArgumentParser:
@@ -403,12 +455,7 @@ def _sync_named_profile(arguments: argparse.Namespace) -> dict[str, object]:
         now=now,
         profile_name=arguments.profile_name,
     )
-    return {
-        JSON_LINKED_KEY: list(report.all_linked),
-        JSON_MOVED_ASIDE_KEY: list(report.all_moved_aside),
-        JSON_UNLINKED_KEY: list(report.all_unlinked),
-        JSON_LAUNCHER_KEY: str(launcher_path),
-    }
+    return {**sync_report_payload(report), JSON_LAUNCHER_KEY: str(launcher_path)}
 
 
 if __name__ == "__main__":

package/scripts/codex_account_choice.py

@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
 """Name the Codex account a runner job uses, and keep each account's home ready.
 
-Up to four Codex accounts sign in, each under its own Codex home in
-``~/.codex-profiles/<name>``. Jobs try them in one fixed order::
+Each Codex account signs in under its own Codex home in
+``~/.codex-profiles/<name>``. The account roster 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. Jobs try them in that order::
 
     first account with more than 10% left              -> normal, that account
     none over 10%, the roomiest one over 1%            -> luna, stop at 1% left
@@ -10,7 +13,7 @@ Up to four Codex accounts sign in, each under its own Codex home in
     none over 1%, or no meter reads                    -> wait, name the first reset
     account not signed in, or its meter unread         -> skipped
 
-Three commands::
+Five commands::
 
     python codex_account_choice.py choose
     {"tier": "normal", "account": "codex-1", "codex_home": "C:/Users/me/.codex-profiles/codex-1",
@@ -21,8 +24,15 @@ Three commands::
     exit 0 while codex-2 has more than 1% left, exit 3 once it has not
 
     python codex_account_choice.py sync
-    links the shared Codex setup (config, rules, skills, plugins) into every
-    account's home and leaves each sign-in and history its own
+    links the shared Codex setup (config, rules, skills, plugins, agents) into
+    every roster account's home and leaves each sign-in and history its own
+
+    python codex_account_choice.py setup
+    asks for each account name, saves the roster, and writes one
+    codex-<name>.cmd launcher per account; a dropped name's launcher moves aside
+
+    python codex_account_choice.py install
+    reruns the setup without asking: syncs every saved account's home and launcher
 """
 
 from __future__ import annotations
@@ -36,21 +46,42 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
-from claude_account_profile import sync_profile
+from claude_account_profile import (
+    launcher_path,
+    move_launcher_aside,
+    sync_profile,
+    sync_report_payload,
+    validate_profile_name,
+    write_launcher,
+)
 from codex_account_meters import (
     CodexAccountMeters,
     CodexMeterUnreadError,
     read_codex_meters,
     resolve_codex_path,
 )
+from dev_env_scripts_constants.claude_account_constants import (
+    ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS,
+    JSON_LAUNCHER_KEY,
+)
 from dev_env_scripts_constants.codex_account_constants import (
     ALL_CODEX_ACCOUNT_NAMES,
     ALL_SHARED_CODEX_HOME_NAMES,
+    CODEX_ACCOUNT_LAUNCHERS_FILE_NAME,
+    CODEX_ACCOUNT_NAME_SEPARATOR,
+    CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
     CODEX_AUTH_FILE_NAME,
+    CODEX_LAUNCHER_FILE_NAME_TEMPLATE,
+    CODEX_LAUNCHER_TEXT_TEMPLATE,
     CODEX_PROFILES_ROOT_DIRECTORY_NAME,
     CODEX_PROFILES_ROOT_ENVIRONMENT_VARIABLE,
+    COMMAND_INSTALL,
+    COMMAND_SETUP,
     EXIT_CODE_NO_ROOM,
     EXIT_CODE_ROOM,
+    INVALID_ACCOUNT_ROSTER_TEMPLATE,
+    JSON_INSTALLED_KEY,
+    JSON_RETIRED_KEY,
     LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
     LUNA_TIER_STOP_PERCENT_LEFT,
     MAIN_CODEX_HOME_DIRECTORY_NAME,
@@ -59,14 +90,28 @@ from dev_env_scripts_constants.codex_account_constants import (
     REASON_NORMAL_TEMPLATE,
     REASON_WAIT_TEMPLATE,
     REASON_WAIT_UNREAD,
+    ROSTER_JSON_INDENT,
+    ROSTER_NOT_A_LIST_TEMPLATE,
+    SETUP_NAMES_SEPARATOR,
+    SETUP_NO_SAVED_NAMES_TEXT,
+    SETUP_PROMPT_TEXT,
+    SETUP_SAVED_NAMES_TEMPLATE,
+    TEXT_ENCODING,
     TIER_LUNA,
     TIER_NORMAL,
     TIER_WAIT,
+    UNKNOWN_ACCOUNT_TEMPLATE,
     UNKNOWN_RESET_TEXT,
     UNREAD_NOT_SIGNED_IN,
 )
 
 MeterReader = Callable[[Path], CodexAccountMeters]
+LineReader = Callable[[str], str]
+LineWriter = Callable[[str], None]
+
+
+class CodexAccountNameError(ValueError):
+    """An account name from the roster or the command line is invalid or unknown."""
 
 
 @dataclass(frozen=True)
@@ -120,6 +165,263 @@ def is_account_local_codex_entry(entry_name: str) -> bool:
     return entry_name not in ALL_SHARED_CODEX_HOME_NAMES
 
 
+def _validated_name(name: str, source: str) -> str:
+    try:
+        return validate_profile_name(name)
+    except ValueError as error:
+        raise CodexAccountNameError(
+            INVALID_ACCOUNT_ROSTER_TEMPLATE.format(source=source, name=name, reason=error)
+        ) from error
+
+
+def _roster(all_raw_names: Sequence[str], source: str) -> tuple[str, ...]:
+    return tuple(
+        dict.fromkeys(_validated_name(each_name, source) for each_name in all_raw_names)
+    )
+
+
+def _environment_roster() -> tuple[str, ...]:
+    raw_roster = os.environ.get(CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE, "")
+    all_stripped = (
+        each_part.strip() for each_part in raw_roster.split(CODEX_ACCOUNT_NAME_SEPARATOR)
+    )
+    all_raw_names = [each_name for each_name in all_stripped if each_name]
+    return _roster(all_raw_names, CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE)
+
+
+def _saved_roster_file_names(profiles_root: Path) -> tuple[str, ...]:
+    """Read the roster saved under the profiles root, ignoring the environment.
+
+    Args:
+        profiles_root: The directory that holds every account's Codex home.
+
+    Returns:
+        The saved names in order, or nothing when no roster file exists.
+
+    Raises:
+        CodexAccountNameError: When the file holds anything but valid names.
+    """
+    roster_path = profiles_root / CODEX_ACCOUNT_LAUNCHERS_FILE_NAME
+    if not roster_path.is_file():
+        return ()
+    try:
+        document = json.loads(roster_path.read_text(encoding=TEXT_ENCODING))
+    except json.JSONDecodeError:
+        document = None
+    if not isinstance(document, list) or not all(
+        isinstance(each_name, str) for each_name in document
+    ):
+        raise CodexAccountNameError(ROSTER_NOT_A_LIST_TEMPLATE.format(source=roster_path))
+    return _roster(document, str(roster_path))
+
+
+def saved_codex_account_names(profiles_root: Path) -> tuple[str, ...]:
+    """Name the account roster, in try order, without duplicates.
+
+    ::
+
+        CODEX_ACCOUNT_PROFILES="alpha, beta,alpha" -> ("alpha", "beta")
+        unset, account-launchers.json ["gamma"]    -> ("gamma",)
+        unset, no file                             -> ()
+
+    Args:
+        profiles_root: The directory that holds every account's Codex home.
+
+    Returns:
+        The environment's names when it names any, else the saved file's names.
+
+    Raises:
+        CodexAccountNameError: When the environment or the file names an invalid account.
+    """
+    return _environment_roster() or _saved_roster_file_names(profiles_root)
+
+
+def codex_account_names(profiles_root: Path) -> tuple[str, ...]:
+    """Name the accounts ``choose``, ``sync``, and ``check`` work on, in try order.
+
+    Args:
+        profiles_root: The directory that holds every account's Codex home.
+
+    Returns:
+        The account roster, else ``codex-1`` through ``codex-4``.
+    """
+    return saved_codex_account_names(profiles_root) or ALL_CODEX_ACCOUNT_NAMES
+
+
+def save_codex_account_names(profiles_root: Path, all_names: Sequence[str]) -> None:
+    """Write the account roster as a JSON list under the profiles root.
+
+    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)
+    )
+
+
+def _sync_account(
+    *, main_home: Path, profiles_root: Path, name: str, now: datetime
+) -> dict[str, object]:
+    report = sync_profile(
+        main_home=main_home,
+        profile_home=profiles_root / name,
+        now=now,
+        is_local=is_account_local_codex_entry,
+    )
+    return sync_report_payload(report)
+
+
+def _install_account(
+    *, main_home: Path, profiles_root: Path, launcher_directory: Path, name: str, now: datetime
+) -> dict[str, object]:
+    sync_payload = _sync_account(
+        main_home=main_home, profiles_root=profiles_root, name=name, now=now
+    )
+    launcher_path = write_launcher(
+        launcher_directory=launcher_directory,
+        profile_home=profiles_root / name,
+        now=now,
+        profile_name=name,
+        launcher_file_name_template=CODEX_LAUNCHER_FILE_NAME_TEMPLATE,
+        launcher_text_template=CODEX_LAUNCHER_TEXT_TEMPLATE,
+    )
+    return {**sync_payload, JSON_LAUNCHER_KEY: str(launcher_path)}
+
+
+def install_codex_account_launchers(
+    *,
+    main_home: Path,
+    profiles_root: Path,
+    launcher_directory: Path,
+    all_names: Sequence[str],
+    now: datetime,
+) -> dict[str, dict[str, object]]:
+    """Link each account's home to the main Codex home and write its launcher, idempotently.
+
+    Args:
+        main_home: The Codex home that holds the shared setup.
+        profiles_root: The directory that holds every account's Codex home.
+        launcher_directory: The directory on PATH that holds the launchers.
+        all_names: The account names to install.
+        now: The run time that names anything moved aside.
+
+    Returns:
+        Per name, the entries linked, moved aside, and unlinked, and the launcher.
+    """
+    return {
+        each_name: _install_account(
+            main_home=main_home,
+            profiles_root=profiles_root,
+            launcher_directory=launcher_directory,
+            name=each_name,
+            now=now,
+        )
+        for each_name in all_names
+    }
+
+
+def _retire_codex_account_launchers(
+    *, launcher_directory: Path, all_names: Sequence[str], now: datetime
+) -> dict[str, str]:
+    """Move each named account's launcher aside, leaving its Codex home alone.
+
+    Args:
+        launcher_directory: The directory on PATH that holds the launchers.
+        all_names: The account names dropped from the roster.
+        now: The run time that names each moved launcher.
+
+    Returns:
+        Per name with a launcher, the moved launcher's path.
+    """
+    all_retired: dict[str, str] = {}
+    for each_name in all_names:
+        retired_path = launcher_path(
+            launcher_directory, each_name, CODEX_LAUNCHER_FILE_NAME_TEMPLATE
+        )
+        if retired_path.is_file():
+            all_retired[each_name] = str(move_launcher_aside(retired_path, now))
+    return all_retired
+
+
+def _read_account_name(read_line: LineReader) -> str:
+    try:
+        return read_line(SETUP_PROMPT_TEXT).strip()
+    except EOFError:
+        return ""
+
+
+def _prompt_codex_account_names(
+    read_line: LineReader, write_line: LineWriter
+) -> tuple[str, ...]:
+    """Ask for account names until a blank line or the end of input.
+
+    ::
+
+        "alpha", "bad name", "alpha", "beta", "" -> ("alpha", "beta")
+
+    Args:
+        read_line: Shows the prompt and returns one typed line.
+        write_line: Shows why a typed name was refused.
+
+    Returns:
+        The valid names in the order typed, without duplicates.
+    """
+    all_names: list[str] = []
+    while entered_name := _read_account_name(read_line):
+        try:
+            all_names.append(validate_profile_name(entered_name))
+        except ValueError as error:
+            write_line(str(error))
+    return tuple(dict.fromkeys(all_names))
+
+
+def _ask_roster(
+    profiles_root: Path, read_line: LineReader, write_line: LineWriter
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    all_saved = _saved_roster_file_names(profiles_root)
+    write_line(
+        SETUP_SAVED_NAMES_TEMPLATE.format(
+            names=SETUP_NAMES_SEPARATOR.join(all_saved) or SETUP_NO_SAVED_NAMES_TEXT
+        )
+    )
+    all_names = _prompt_codex_account_names(read_line, write_line)
+    all_dropped = tuple(
+        each_name for each_name in all_saved if each_name not in all_names
+    )
+    return all_names, all_dropped
+
+
+def update_codex_account_roster(
+    *,
+    profiles_root: Path,
+    launcher_directory: Path,
+    now: datetime,
+    read_line: LineReader = input,
+    write_line: LineWriter = print,
+) -> tuple[tuple[str, ...], dict[str, str]]:
+    """Ask for the account roster, save it, and move dropped launchers aside.
+
+    Args:
+        profiles_root: The directory that holds every account's Codex home.
+        launcher_directory: The directory on PATH that holds the launchers.
+        now: The run time that names each moved launcher.
+        read_line: Shows the prompt and returns one typed line.
+        write_line: Shows the saved roster and each refused name.
+
+    Returns:
+        The new roster, and per dropped name, the moved launcher's path.
+    """
+    all_names, all_dropped = _ask_roster(profiles_root, read_line, write_line)
+    all_retired = _retire_codex_account_launchers(
+        launcher_directory=launcher_directory, all_names=all_dropped, now=now
+    )
+    save_codex_account_names(profiles_root, all_names)
+    return all_names, all_retired
+
+
 def read_account(
     name: str, profiles_root: Path, read_meters: MeterReader
 ) -> AccountReading:
@@ -320,7 +622,7 @@ def _run_choose(arguments: argparse.Namespace) -> int:
     read_meters = _meter_reader(arguments.codex_path)
     all_readings = [
         read_account(each_name, arguments.profiles_root, read_meters)
-        for each_name in ALL_CODEX_ACCOUNT_NAMES
+        for each_name in codex_account_names(arguments.profiles_root)
     ]
     print(
         json.dumps(decision_payload(choose_codex_account(all_readings), all_readings))
@@ -328,7 +630,18 @@ def _run_choose(arguments: argparse.Namespace) -> int:
     return 0
 
 
+def _require_known_account(name: str, profiles_root: Path) -> None:
+    all_known = codex_account_names(profiles_root)
+    if name not in all_known:
+        raise CodexAccountNameError(
+            UNKNOWN_ACCOUNT_TEMPLATE.format(
+                name=name, known=SETUP_NAMES_SEPARATOR.join(all_known)
+            )
+        )
+
+
 def _run_check(arguments: argparse.Namespace) -> int:
+    _require_known_account(arguments.account, arguments.profiles_root)
     reading = read_account(
         arguments.account, arguments.profiles_root, _meter_reader(arguments.codex_path)
     )
@@ -340,23 +653,70 @@ def _run_check(arguments: argparse.Namespace) -> int:
 
 def _run_sync(arguments: argparse.Namespace) -> int:
     now = datetime.now(timezone.utc)
-    all_reports = {}
-    for each_name in ALL_CODEX_ACCOUNT_NAMES:
-        report = sync_profile(
+    all_reports = {
+        each_name: _sync_account(
             main_home=arguments.main_home,
-            profile_home=arguments.profiles_root / each_name,
+            profiles_root=arguments.profiles_root,
+            name=each_name,
             now=now,
-            is_local=is_account_local_codex_entry,
         )
-        all_reports[each_name] = {
-            "linked": list(report.all_linked),
-            "moved_aside": list(report.all_moved_aside),
-            "unlinked": list(report.all_unlinked),
-        }
+        for each_name in codex_account_names(arguments.profiles_root)
+    }
+    print(json.dumps(all_reports))
+    return 0
+
+
+def _run_install(arguments: argparse.Namespace) -> int:
+    all_reports = install_codex_account_launchers(
+        main_home=arguments.main_home,
+        profiles_root=arguments.profiles_root,
+        launcher_directory=arguments.launcher_directory,
+        all_names=saved_codex_account_names(arguments.profiles_root),
+        now=datetime.now(timezone.utc),
+    )
     print(json.dumps(all_reports))
     return 0
 
 
+def _run_setup(arguments: argparse.Namespace) -> int:
+    now = datetime.now(timezone.utc)
+    all_names, all_retired = update_codex_account_roster(
+        profiles_root=arguments.profiles_root,
+        launcher_directory=arguments.launcher_directory,
+        now=now,
+    )
+    all_installed = install_codex_account_launchers(
+        main_home=arguments.main_home,
+        profiles_root=arguments.profiles_root,
+        launcher_directory=arguments.launcher_directory,
+        all_names=all_names,
+        now=now,
+    )
+    print(json.dumps({JSON_INSTALLED_KEY: all_installed, JSON_RETIRED_KEY: all_retired}))
+    return 0
+
+
+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
+    )
+
+
+def _add_launcher_commands(
+    all_commands: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    all_launcher_commands = ((COMMAND_SETUP, _run_setup), (COMMAND_INSTALL, _run_install))
+    for each_command, each_run in all_launcher_commands:
+        command_parser = all_commands.add_parser(each_command)
+        _add_main_home_argument(command_parser)
+        command_parser.add_argument(
+            "--launcher-directory",
+            type=Path,
+            default=Path.home().joinpath(*ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS),
+        )
+        command_parser.set_defaults(run=each_run)
+
+
 def _build_argument_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Name the Codex account a runner job uses."
@@ -366,16 +726,15 @@ def _build_argument_parser() -> argparse.ArgumentParser:
     all_commands = parser.add_subparsers(dest="command", required=True)
     all_commands.add_parser("choose").set_defaults(run=_run_choose)
     check_parser = all_commands.add_parser("check")
-    check_parser.add_argument("account", choices=ALL_CODEX_ACCOUNT_NAMES)
+    check_parser.add_argument("account")
     check_parser.add_argument(
         "--floor", type=float, default=LUNA_TIER_STOP_PERCENT_LEFT
     )
     check_parser.set_defaults(run=_run_check)
     sync_parser = all_commands.add_parser("sync")
-    sync_parser.add_argument(
-        "--main-home", type=Path, default=Path.home() / MAIN_CODEX_HOME_DIRECTORY_NAME
-    )
+    _add_main_home_argument(sync_parser)
     sync_parser.set_defaults(run=_run_sync)
+    _add_launcher_commands(all_commands)
     return parser
 
 
@@ -386,10 +745,16 @@ def main(all_command_arguments: list[str]) -> int:
         all_command_arguments: Command-line arguments after the program name.
 
     Returns:
-        Zero for choose and sync; for check, zero with room and three without.
+        Zero for choose, sync, setup, and install; for check, zero with room and
+        three without. An invalid or unknown account name exits through the
+        parser with two.
     """
-    arguments = _build_argument_parser().parse_args(all_command_arguments)
-    return arguments.run(arguments)
+    parser = _build_argument_parser()
+    arguments = parser.parse_args(all_command_arguments)
+    try:
+        return arguments.run(arguments)
+    except CodexAccountNameError as error:
+        parser.error(str(error))
 
 
 if __name__ == "__main__":

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -2,13 +2,75 @@
 
 Each account signs in under its own Codex home. The picker reads every
 account's rate-limit windows through ``codex app-server`` and names the account
-a job runs on, trying the accounts in one fixed order.
+a job runs on, trying the accounts in roster order.
 """
 
 from __future__ import annotations
 
 ALL_CODEX_ACCOUNT_NAMES: tuple[str, ...] = ("codex-1", "codex-2", "codex-3", "codex-4")
-"""Codex accounts in the order jobs try them. The names say nothing about a plan."""
+"""Fallback Codex accounts, in try order, when no account roster is saved or set."""
+
+CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE: str = "CODEX_ACCOUNT_PROFILES"
+"""Environment variable naming the account roster, comma-separated, over the saved file."""
+
+CODEX_ACCOUNT_LAUNCHERS_FILE_NAME: str = "account-launchers.json"
+"""File under the profiles root that holds the saved account roster as a JSON list."""
+
+CODEX_ACCOUNT_NAME_SEPARATOR: str = ","
+"""Separator between account names in the roster environment variable."""
+
+CODEX_LAUNCHER_FILE_NAME_TEMPLATE: str = "codex-{profile_name}.cmd"
+"""File name pattern for one account's Codex launcher."""
+
+CODEX_LAUNCHER_TEXT_TEMPLATE: str = (
+    "@echo off\r\n"
+    "setlocal\r\n"
+    'set "CODEX_HOME={profile_home}"\r\n'
+    "call codex %*\r\n"
+    "exit /b %ERRORLEVEL%\r\n"
+)
+"""Launcher body: point Codex at the account's home and pass every argument through.
+
+``codex`` resolves to npm's ``codex.cmd``, whose last line runs ``endLocal`` and a
+``goto`` to a missing label. Chained into without ``call``, that line ends this
+launcher's ``setlocal`` too, and Codex starts without ``CODEX_HOME``.
+"""
+
+SETUP_PROMPT_TEXT: str = "Name for this Codex account launcher (blank to finish): "
+"""Prompt the setup command shows for each account name."""
+
+SETUP_SAVED_NAMES_TEMPLATE: str = "Saved Codex account launchers: {names}"
+"""Line the setup command prints first, naming the saved roster."""
+
+SETUP_NO_SAVED_NAMES_TEXT: str = "none"
+"""Saved-roster text when no account launcher is saved."""
+
+SETUP_NAMES_SEPARATOR: str = ", "
+"""Separator between names on the setup command's saved-roster line."""
+
+INVALID_ACCOUNT_ROSTER_TEMPLATE: str = "{source} names {name!r}: {reason}"
+"""Error when the roster environment variable or file names an invalid account."""
+
+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."""
+
+ROSTER_JSON_INDENT: int = 2
+"""Indent of the saved roster JSON, one name per line."""
+
+COMMAND_SETUP: str = "setup"
+"""Command that asks for the roster, saves it, and installs every launcher."""
+
+COMMAND_INSTALL: str = "install"
+"""Command that installs every saved roster account without asking."""
+
+UNKNOWN_ACCOUNT_TEMPLATE: str = "unknown Codex account {name!r}; known: {known}"
+"""Error when ``check`` names an account outside the roster."""
+
+JSON_INSTALLED_KEY: str = "installed"
+"""Setup JSON key holding the install report for every roster account."""
+
+JSON_RETIRED_KEY: str = "retired"
+"""Setup JSON key holding each dropped account and where its launcher moved."""
 
 CODEX_PROFILES_ROOT_DIRECTORY_NAME: str = ".codex-profiles"
 """Directory under the user home that holds one Codex home per account."""
@@ -28,6 +90,7 @@ CODEX_AUTH_FILE_NAME: str = "auth.json"
 ALL_SHARED_CODEX_HOME_NAMES: frozenset[str] = frozenset(
     {
         "AGENTS.md",
+        "agents",
         "config.toml",
         "hooks",
         "hooks.json",

package/scripts/test_claude_account_profile.py

@@ -46,6 +46,16 @@ class TestDefaultProfileHome:
         assert profile.default_profile_home() == tmp_path / ".claude-profiles" / "ev"
 
 
+class TestValidateProfileName:
+    def test_should_accept_letters_digits_hyphens_and_underscores(self) -> None:
+        assert profile.validate_profile_name("alpha_2-b") == "alpha_2-b"
+
+    @pytest.mark.parametrize("profile_name", ["bad name", "-alpha", "CON", "main", "wait"])
+    def test_should_refuse_an_unsafe_or_reserved_name(self, profile_name: str) -> None:
+        with pytest.raises(ValueError):
+            profile.validate_profile_name(profile_name)
+
+
 class TestIsAccountLocal:
     def test_should_keep_sign_in_state_and_history_local(self) -> None:
         for each_name in (
@@ -211,6 +221,30 @@ class TestWriteLauncher:
         )
         assert moved_launcher.read_text(encoding="utf-8") == "old launcher"
 
+    def test_should_write_the_launcher_from_the_callers_templates(
+        self, tmp_path: Path
+    ) -> None:
+        launcher_path = profile.write_launcher(
+            launcher_directory=tmp_path / "bin",
+            profile_home=tmp_path / "alpha",
+            now=NOW,
+            profile_name="alpha",
+            launcher_file_name_template="tool-{profile_name}.cmd",
+            launcher_text_template="home={profile_home}",
+        )
+        assert launcher_path == tmp_path / "bin" / "tool-alpha.cmd"
+        assert launcher_path.read_text(encoding="utf-8") == f"home={tmp_path / 'alpha'}"
+
+
+class TestMoveLauncherAside:
+    def test_should_rename_the_launcher_with_the_run_time(self, tmp_path: Path) -> None:
+        launcher_path = tmp_path / "tool-alpha.cmd"
+        launcher_path.write_text("launcher", encoding="utf-8")
+        moved_path = profile.move_launcher_aside(launcher_path, NOW)
+        assert moved_path == tmp_path / "tool-alpha.cmd.replaced-20260922T210000Z"
+        assert moved_path.read_text(encoding="utf-8") == "launcher"
+        assert not launcher_path.exists()
+
 
 class TestMain:
     def test_should_print_what_the_sync_changed(

package/scripts/test_codex_account_choice.py

@@ -4,15 +4,85 @@ from __future__ import annotations
 
 import json
 import os
+import subprocess
+from collections.abc import Callable, Iterator
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 import pytest
 
 import codex_account_choice as choice
+from claude_account_profile import links_to
 from codex_account_meters import CodexAccountMeters, CodexMeterUnreadError, UsageWindow
 
 NOW = datetime(2026, 9, 23, 17, 0, tzinfo=timezone.utc)
+ALL_SHARED_ENTRY_NAMES = (
+    "AGENTS.md",
+    "agents",
+    "config.toml",
+    "hooks",
+    "hooks.json",
+    "plugins",
+    "rules",
+    "skills",
+)
+NPM_CODEX_SHIM_TEXT = (
+    "@ECHO off\r\n"
+    "GOTO start\r\n"
+    ":find_dp0\r\n"
+    "SET dp0=%~dp0\r\n"
+    "EXIT /b\r\n"
+    ":start\r\n"
+    "SETLOCAL\r\n"
+    "CALL :find_dp0\r\n"
+    'SET "_prog=cmd"\r\n'
+    "endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% &"
+    ' "%_prog%" /d /c "echo %%CODEX_HOME%%"\r\n'
+)
+
+
+@pytest.fixture(autouse=True)
+def clear_account_roster_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CODEX_ACCOUNT_PROFILES", raising=False)
+
+
+def build_codex_main_home(tmp_path: Path) -> Path:
+    main_home = tmp_path / "main"
+    for each_directory in ("agents", "hooks", "plugins", "rules", "skills", "sessions"):
+        (main_home / each_directory).mkdir(parents=True)
+    for each_file in ("AGENTS.md", "config.toml", "hooks.json", "auth.json", "history.jsonl"):
+        (main_home / each_file).write_text(each_file, encoding="utf-8")
+    return main_home
+
+
+def save_roster(profiles_root: Path, document: object) -> None:
+    profiles_root.mkdir(parents=True, exist_ok=True)
+    (profiles_root / "account-launchers.json").write_text(
+        json.dumps(document), encoding="utf-8"
+    )
+
+
+def typed_lines(*all_lines: str) -> Callable[[str], str]:
+    remaining_lines: Iterator[str] = iter(all_lines)
+
+    def read_line(prompt: str) -> str:
+        assert prompt == "Name for this Codex account launcher (blank to finish): "
+        try:
+            return next(remaining_lines)
+        except StopIteration as error:
+            raise EOFError from error
+
+    return read_line
+
+
+def install(main_home: Path, tmp_path: Path, *all_names: str) -> dict[str, dict[str, object]]:
+    return choice.install_codex_account_launchers(
+        main_home=main_home,
+        profiles_root=tmp_path / "profiles",
+        launcher_directory=tmp_path / "bin",
+        all_names=all_names,
+        now=NOW,
+    )
 
 
 def reading(
@@ -251,7 +321,7 @@ class TestSync:
 class TestSmallHelpers:
     @pytest.mark.parametrize(
         ("entry_name", "is_local"),
-        [("auth.json", True), ("sessions", True), ("state_5.sqlite", True), ("config.toml", False), ("plugins", False)],
+        [("auth.json", True), ("sessions", True), ("state_5.sqlite", True), ("config.toml", False), ("plugins", False), ("agents", False)],
     )
     def should_keep_every_entry_outside_the_shared_set_per_account(
         self, entry_name: str, is_local: bool
@@ -274,3 +344,301 @@ class TestSmallHelpers:
         payload = choice.reading_payload(reading("codex-1", weekly_used=40.0, short_used=5.0))
         assert payload["percent_left"] == 60.0
         assert [each["minutes"] for each in payload["windows"]] == [300, 10080]
+
+
+class TestAccountRoster:
+    def should_take_the_environment_roster_over_the_saved_file(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        save_roster(tmp_path, ["gamma"])
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", " beta , alpha,, ")
+        assert choice.saved_codex_account_names(tmp_path) == ("beta", "alpha")
+
+    def should_read_the_saved_file_when_the_environment_is_unset(
+        self, tmp_path: Path
+    ) -> None:
+        save_roster(tmp_path, ["gamma", "alpha"])
+        assert choice.saved_codex_account_names(tmp_path) == ("gamma", "alpha")
+
+    def should_name_no_account_when_neither_is_set(self, tmp_path: Path) -> None:
+        assert choice.saved_codex_account_names(tmp_path) == ()
+
+    def should_refuse_an_invalid_name_from_the_environment(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha,bad name")
+        with pytest.raises(ValueError, match="CODEX_ACCOUNT_PROFILES names 'bad name'"):
+            choice.saved_codex_account_names(tmp_path)
+
+    @pytest.mark.parametrize("document", [["alpha", "con"], ["alpha", 3], {"alpha": 1}])
+    def should_refuse_a_saved_file_with_an_invalid_name(
+        self, tmp_path: Path, document: object
+    ) -> None:
+        save_roster(tmp_path, document)
+        with pytest.raises(ValueError, match="account-launchers.json"):
+            choice.saved_codex_account_names(tmp_path)
+
+    def should_refuse_a_saved_file_that_is_not_json(
+        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        (tmp_path / "account-launchers.json").write_text('["alpha",', encoding="utf-8")
+        with pytest.raises(SystemExit) as exit_info:
+            choice.main(["--profiles-root", str(tmp_path), "check", "alpha"])
+        assert exit_info.value.code == 2
+        assert "account-launchers.json" in capsys.readouterr().err
+
+    def should_drop_duplicates_and_keep_the_first_order(self, tmp_path: Path) -> None:
+        save_roster(tmp_path, ["beta", "alpha", "beta", "gamma", "alpha"])
+        assert choice.saved_codex_account_names(tmp_path) == ("beta", "alpha", "gamma")
+
+    def should_save_the_roster_as_a_json_list_ending_in_a_newline(
+        self, tmp_path: Path
+    ) -> None:
+        profiles_root = tmp_path / "profiles"
+        choice.save_codex_account_names(profiles_root, ("alpha", "beta"))
+        assert (profiles_root / "account-launchers.json").read_bytes() == (
+            b'[\n  "alpha",\n  "beta"\n]\n'
+        )
+        assert choice.saved_codex_account_names(profiles_root) == ("alpha", "beta")
+
+    def should_fall_back_to_the_four_fixed_accounts_without_a_roster(
+        self, tmp_path: Path
+    ) -> None:
+        assert choice.codex_account_names(tmp_path) == (
+            "codex-1",
+            "codex-2",
+            "codex-3",
+            "codex-4",
+        )
+
+
+class TestRosterDrivesTheJobCommands:
+    def should_try_the_roster_in_order_and_skip_the_fixed_accounts(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        all_weekly_used = {"beta": 95.0, "alpha": 50.0, "codex-1": 0.0}
+        for each_name in all_weekly_used:
+            (tmp_path / each_name).mkdir()
+            (tmp_path / each_name / "auth.json").write_text("{}")
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "beta,alpha")
+        monkeypatch.setattr(
+            choice,
+            "_meter_reader",
+            lambda codex_path: (
+                lambda codex_home: CodexAccountMeters(
+                    (UsageWindow(10080, all_weekly_used[codex_home.name], None),)
+                )
+            ),
+        )
+        assert choice.main(["--profiles-root", str(tmp_path), "choose"]) == 0
+        payload = json.loads(capsys.readouterr().out)
+        assert (payload["tier"], payload["account"]) == ("normal", "alpha")
+        assert [each["name"] for each in payload["accounts"]] == ["beta", "alpha"]
+
+    def should_choose_among_the_four_fixed_accounts_without_a_roster(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        monkeypatch.setattr(choice, "_meter_reader", lambda codex_path: None)
+        assert choice.main(["--profiles-root", str(tmp_path), "choose"]) == 0
+        payload = json.loads(capsys.readouterr().out)
+        assert [each["name"] for each in payload["accounts"]] == [
+            "codex-1",
+            "codex-2",
+            "codex-3",
+            "codex-4",
+        ]
+
+    def should_sync_only_the_roster_accounts(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        main_home = build_codex_main_home(tmp_path)
+        profiles_root = tmp_path / "profiles"
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "alpha")
+        all_arguments = ["--profiles-root", str(profiles_root), "sync"]
+        assert choice.main([*all_arguments, "--main-home", str(main_home)]) == 0
+        assert list(json.loads(capsys.readouterr().out)) == ["alpha"]
+        assert links_to(profiles_root / "alpha" / "agents", main_home / "agents")
+        assert not (profiles_root / "codex-1").exists()
+
+    def should_check_a_saved_roster_account(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        save_roster(tmp_path, ["alpha"])
+        (tmp_path / "alpha").mkdir()
+        (tmp_path / "alpha" / "auth.json").write_text("{}")
+        monkeypatch.setattr(
+            choice,
+            "_meter_reader",
+            lambda codex_path: (
+                lambda codex_home: CodexAccountMeters((UsageWindow(10080, 40.0, None),))
+            ),
+        )
+        assert choice.main(["--profiles-root", str(tmp_path), "check", "alpha"]) == 0
+
+    @pytest.mark.parametrize("account", ["gamma", "codex-1"])
+    def should_refuse_to_check_an_account_outside_the_roster(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, account: str
+    ) -> None:
+        save_roster(tmp_path, ["alpha"])
+        monkeypatch.setattr(choice, "_meter_reader", lambda codex_path: None)
+        with pytest.raises(SystemExit) as exit_info:
+            choice.main(["--profiles-root", str(tmp_path), "check", account])
+        assert exit_info.value.code == 2
+
+
+class TestInstallLaunchers:
+    def should_link_the_shared_setup_and_keep_each_sign_in_per_account(
+        self, tmp_path: Path
+    ) -> None:
+        main_home = build_codex_main_home(tmp_path)
+        report = install(main_home, tmp_path, "alpha", "beta")
+        assert list(report) == ["alpha", "beta"]
+        for each_name in ("alpha", "beta"):
+            each_home = tmp_path / "profiles" / each_name
+            for each_entry in ALL_SHARED_ENTRY_NAMES:
+                assert links_to(each_home / each_entry, main_home / each_entry)
+            for each_local_entry in ("auth.json", "history.jsonl", "sessions"):
+                assert not os.path.lexists(each_home / each_local_entry)
+            assert report[each_name]["launcher"] == str(
+                tmp_path / "bin" / f"codex-{each_name}.cmd"
+            )
+
+    def should_change_nothing_on_a_second_run(self, tmp_path: Path) -> None:
+        main_home = build_codex_main_home(tmp_path)
+        install(main_home, tmp_path, "alpha")
+        launcher_path = tmp_path / "bin" / "codex-alpha.cmd"
+        first_launcher_bytes = launcher_path.read_bytes()
+        second_report = install(main_home, tmp_path, "alpha")
+        assert second_report["alpha"]["linked"] == []
+        assert second_report["alpha"]["moved_aside"] == []
+        assert second_report["alpha"]["unlinked"] == []
+        assert launcher_path.read_bytes() == first_launcher_bytes
+        assert sorted(each.name for each in (tmp_path / "bin").iterdir()) == [
+            "codex-alpha.cmd"
+        ]
+
+    def should_set_codex_home_and_call_codex_in_the_launcher(
+        self, tmp_path: Path
+    ) -> None:
+        install(build_codex_main_home(tmp_path), tmp_path, "alpha")
+        launcher_lines = (tmp_path / "bin" / "codex-alpha.cmd").read_bytes().split(b"\r\n")
+        profile_home = tmp_path / "profiles" / "alpha"
+        assert f'set "CODEX_HOME={profile_home}"'.encode() in launcher_lines
+        assert b"call codex %*" in launcher_lines
+
+    def should_install_the_environment_roster_from_the_command_line(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        main_home = build_codex_main_home(tmp_path)
+        save_roster(tmp_path / "profiles", ["gamma"])
+        monkeypatch.setenv("CODEX_ACCOUNT_PROFILES", "beta")
+        all_arguments = [
+            "--profiles-root",
+            str(tmp_path / "profiles"),
+            "install",
+            "--main-home",
+            str(main_home),
+            "--launcher-directory",
+            str(tmp_path / "bin"),
+        ]
+        assert choice.main(all_arguments) == 0
+        assert list(json.loads(capsys.readouterr().out)) == ["beta"]
+        assert (tmp_path / "bin" / "codex-beta.cmd").is_file()
+        assert not (tmp_path / "bin" / "codex-gamma.cmd").exists()
+
+    def should_print_an_empty_report_for_an_empty_roster(
+        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        all_arguments = ["--profiles-root", str(tmp_path / "profiles"), "install"]
+        assert choice.main([*all_arguments, "--launcher-directory", str(tmp_path / "bin")]) == 0
+        assert json.loads(capsys.readouterr().out) == {}
+        assert not (tmp_path / "bin").exists()
+
+
+class TestSetupRoster:
+    def should_save_each_valid_name_once_in_typed_order(self, tmp_path: Path) -> None:
+        all_shown: list[str] = []
+        all_names, all_retired = choice.update_codex_account_roster(
+            profiles_root=tmp_path,
+            launcher_directory=tmp_path / "bin",
+            now=NOW,
+            read_line=typed_lines("alpha", "bad name", "alpha", "beta", "", "gamma"),
+            write_line=all_shown.append,
+        )
+        assert (all_names, all_retired) == (("alpha", "beta"), {})
+        assert choice.saved_codex_account_names(tmp_path) == ("alpha", "beta")
+        assert all_shown == [
+            "Saved Codex account launchers: none",
+            "profile name must use letters, digits, hyphens, or underscores",
+        ]
+
+    def should_finish_at_the_end_of_input(self, tmp_path: Path) -> None:
+        all_names, _ = choice.update_codex_account_roster(
+            profiles_root=tmp_path,
+            launcher_directory=tmp_path / "bin",
+            now=NOW,
+            read_line=typed_lines("gamma"),
+            write_line=lambda line: None,
+        )
+        assert all_names == ("gamma",)
+
+    def should_move_a_dropped_launcher_aside_and_keep_its_home(
+        self, tmp_path: Path
+    ) -> None:
+        main_home = build_codex_main_home(tmp_path)
+        profiles_root = tmp_path / "profiles"
+        choice.save_codex_account_names(profiles_root, ("alpha", "beta"))
+        install(main_home, tmp_path, "alpha", "beta")
+        (profiles_root / "beta" / "auth.json").write_text("beta sign-in", encoding="utf-8")
+        all_shown: list[str] = []
+        all_names, all_retired = choice.update_codex_account_roster(
+            profiles_root=profiles_root,
+            launcher_directory=tmp_path / "bin",
+            now=NOW,
+            read_line=typed_lines("alpha", ""),
+            write_line=all_shown.append,
+        )
+        moved_launcher = tmp_path / "bin" / "codex-beta.cmd.replaced-20260923T170000Z"
+        assert all_names == ("alpha",)
+        assert all_retired == {"beta": str(moved_launcher)}
+        assert all_shown == ["Saved Codex account launchers: alpha, beta"]
+        assert moved_launcher.is_file()
+        assert not (tmp_path / "bin" / "codex-beta.cmd").exists()
+        assert (tmp_path / "bin" / "codex-alpha.cmd").is_file()
+        assert (profiles_root / "beta" / "auth.json").read_text(encoding="utf-8") == (
+            "beta sign-in"
+        )
+        assert choice.saved_codex_account_names(profiles_root) == ("alpha",)
+
+
+class TestCodexLauncher:
+    @pytest.mark.skipif(os.name != "nt", reason="runs the launcher through cmd.exe")
+    def should_hand_codex_home_to_the_npm_codex_shim(self, tmp_path: Path) -> None:
+        install(build_codex_main_home(tmp_path), tmp_path, "alpha")
+        launcher_path = tmp_path / "bin" / "codex-alpha.cmd"
+        fake_directory = tmp_path / "fake"
+        fake_directory.mkdir()
+        (fake_directory / "codex.cmd").write_bytes(NPM_CODEX_SHIM_TEXT.encode("utf-8"))
+        environment = dict(os.environ)
+        environment["PATH"] = str(fake_directory) + os.pathsep + environment["PATH"]
+        environment["CODEX_HOME"] = str(tmp_path / "decoy")
+        completed = subprocess.run(
+            ["cmd", "/c", str(launcher_path)],
+            env=environment,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert completed.stdout.strip() == str(tmp_path / "profiles" / "alpha")