claude-dev-env 8.34.0 → 8.35.1

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,41 @@ 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_PROGRAM,
     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 +89,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 +164,260 @@ 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_program=CODEX_LAUNCHER_PROGRAM,
+    )
+    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_PROGRAM)
+        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 +618,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 +626,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 +649,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 +722,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 +741,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/claude_account_constants.py

@@ -8,8 +8,11 @@ main account so its owner never runs out.
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from datetime import timedelta
 
+from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
+
 MAIN_CLAUDE_HOME_DIRECTORY_NAME: str = ".claude"
 """Directory under the user home that holds the main account's Claude home."""
 
@@ -38,22 +41,39 @@ ALL_WINDOWS_RESERVED_PROFILE_NAMES: frozenset[str] = frozenset(
 ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS: tuple[str, ...] = (".local", "bin")
 """Path parts under the user home of the directory on PATH that holds the launcher."""
 
-LAUNCHER_FILE_NAME_TEMPLATE: str = "claude-{profile_name}.cmd"
-"""File name pattern for a named profile launcher."""
-
-LAUNCHER_FILE_NAME: str = LAUNCHER_FILE_NAME_TEMPLATE.format(
-    profile_name=SECOND_ACCOUNT_PROFILE_NAME
-)
-"""File name of the launcher that runs Claude under the second account."""
+CLAUDE_BINARY_NAME: str = "claude"
+"""Claude command name looked up on PATH."""
 
-LAUNCHER_TEXT_TEMPLATE: str = (
+LAUNCHER_BODY_TEMPLATE: str = (
     "@echo off\r\n"
     "setlocal\r\n"
-    'set "CLAUDE_CONFIG_DIR={profile_home}"\r\n'
-    "claude %*\r\n"
+    'set "{environment_variable}={profile_home}"\r\n'
+    "call {program} %*\r\n"
     "exit /b %ERRORLEVEL%\r\n"
 )
-"""Launcher body: point Claude at the profile and pass every argument through."""
+"""Launcher body: point a program at the profile home and pass every argument through.
+
+The program resolves to npm's ``<program>.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 the program starts without the variable.
+"""
+
+
+@dataclass(frozen=True)
+class LauncherProgram:
+    """The program a profile launcher runs and the variable naming its home."""
+
+    program: str
+    environment_variable: str
+    file_name_template: str
+
+
+CLAUDE_LAUNCHER_PROGRAM: LauncherProgram = LauncherProgram(
+    program=CLAUDE_BINARY_NAME,
+    environment_variable=CLAUDE_CONFIG_DIR_ENV_VAR,
+    file_name_template="claude-{profile_name}.cmd",
+)
+"""Launcher that runs Claude with ``CLAUDE_CONFIG_DIR`` set to the profile home."""
 
 LAUNCHER_REPLACED_SUFFIX: str = ".replaced-"
 """Suffix, before the run time, of an older launcher the sync moved aside."""

package/scripts/dev_env_scripts_constants/claude_account_worker_constants.py

@@ -6,6 +6,7 @@ from dev_env_scripts_constants.claude_account_constants import (
     CHOICE_MAIN,
     CHOICE_SECOND,
     CHOICE_WAIT,
+    CLAUDE_BINARY_NAME,
     CREDENTIALS_FILE_NAME,
     EXTRA_PROFILES_FILE_NAME,
     JSON_ACCOUNT_KEY,
@@ -15,8 +16,6 @@ from dev_env_scripts_constants.claude_account_constants import (
 )
 from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
 
-CLAUDE_BINARY_NAME: str = "claude"
-
 DEFAULT_PERMISSION_MODE: str = "auto"
 
 DEFAULT_TIMEOUT_MINUTES: int = 60

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -2,13 +2,60 @@
 
 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
 
+from dev_env_scripts_constants.claude_account_constants import LauncherProgram
+
 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."""
+
+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 +75,7 @@ CODEX_AUTH_FILE_NAME: str = "auth.json"
 ALL_SHARED_CODEX_HOME_NAMES: frozenset[str] = frozenset(
     {
         "AGENTS.md",
+        "agents",
         "config.toml",
         "hooks",
         "hooks.json",
@@ -71,6 +119,13 @@ ALL_CODEX_BINARY_CANDIDATE_RELATIVE_PARTS: tuple[tuple[str, ...], ...] = (
 CODEX_BINARY_NAME: str = "codex"
 """Codex command name looked up on PATH."""
 
+CODEX_LAUNCHER_PROGRAM: LauncherProgram = LauncherProgram(
+    program=CODEX_BINARY_NAME,
+    environment_variable=CODEX_HOME_ENVIRONMENT_VARIABLE,
+    file_name_template="codex-{profile_name}.cmd",
+)
+"""Launcher that runs Codex with ``CODEX_HOME`` set to the account's home."""
+
 ALL_APP_SERVER_ARGUMENTS: tuple[str, ...] = ("app-server", "--listen", "stdio://")
 """Arguments that start Codex as a JSON-RPC server on standard input and output."""