claude-dev-env 8.12.0 → 8.14.0

package/docs/codex-accounts.md

@@ -0,0 +1,79 @@
+# 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.
+
+## 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_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 |
+
+## 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.
+
+## Sign in once
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py sync
+```
+
+Then, for each account, sign in with that account's home:
+
+```
+$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.
+
+## Which account a job uses
+
+Room is the smaller of an account's two windows: the 5-hour window and the week.
+
+| Condition | Answer |
+|---|---|
+| First account in order with more than 10% left | `normal` on that account |
+| No account over 10%, one or more over 1% | `luna` on the account with the most room, `stop_below_percent` 1 |
+| An account that reports a 5-hour window, with under 20% of that window left | never takes `luna` |
+| No account over 1% | `wait`, naming the account whose blocking windows reset first |
+| Account not signed in, or its meter unread | skipped, with the reason in `accounts` |
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py choose
+{"tier": "normal", "account": "codex-1", "codex_home": "...\\codex-1", "percent_left": 62.0,
+ "stop_below_percent": null, "reason": "codex-1 has 62% left", "accounts": [...]}
+```
+
+A job runs Codex with `CODEX_HOME` set to `codex_home`. On `luna`, the job runs
+Luna and polls `check` between steps:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py check codex-2 --floor 1
+```
+
+`check` exits 0 while the account has more than the floor left, and 3 once it has
+not or its meter is unread. The job stops on 3.
+
+## Shared callers
+
+Two scripts under `_shared` run `choose` by path. Each finds the picker at
+`scripts/codex_account_choice.py` in the directory that holds `_shared`. Once
+installed, that is `~/.claude/scripts/codex_account_choice.py`.
+
+| Caller | What it does with the answer |
+|---|---|
+| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed picker skips the Codex gate |
+| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `codex_home` |
+
+Pass `--codex-path` when `codex` is off PATH. Without it the picker also tries
+the desktop install path under the user home.

package/hooks/blocking/test_duplicate_rmtree_helper_blocker.py

@@ -172,7 +172,7 @@ def test_path_exempts_test_file_suffix() -> None:
 
 def test_path_does_not_exempt_production_module() -> None:
     assert not path_is_exempt(
-        "shared_utils/samsung_utils/cert_failure_processor/failure_categorizer.py"
+        "shared_utils/vendor_utils/cert_failure_processor/failure_categorizer.py"
     )
 
 
@@ -241,7 +241,7 @@ def test_main_blocks_trio_copy_introduced_by_second_multi_edit() -> None:
         {
             "tool_name": "MultiEdit",
             "tool_input": {
-                "file_path": "shared_utils/samsung_utils/cert_failure_processor/parser.py",
+                "file_path": "shared_utils/vendor_utils/cert_failure_processor/parser.py",
                 "edits": [
                     {"old_string": "a = 1", "new_string": "a = 11"},
                     {"old_string": "b = 2", "new_string": COPIED_TRIO},
@@ -261,7 +261,7 @@ def test_main_allows_clean_multi_edit() -> None:
         {
             "tool_name": "MultiEdit",
             "tool_input": {
-                "file_path": "shared_utils/samsung_utils/cert_failure_processor/parser.py",
+                "file_path": "shared_utils/vendor_utils/cert_failure_processor/parser.py",
                 "edits": [
                     {"old_string": "a = 1", "new_string": "a = 11"},
                     {"old_string": "b = 2", "new_string": "b = 22"},
@@ -301,7 +301,7 @@ def test_main_blocks_local_trio_copy_in_production_module() -> None:
             "tool_name": "Write",
             "tool_input": {
                 "file_path": (
-                    "shared_utils/samsung_utils/cert_failure_processor/failure_categorizer.py"
+                    "shared_utils/vendor_utils/cert_failure_processor/failure_categorizer.py"
                 ),
                 "content": COPIED_TRIO,
             },
@@ -319,7 +319,7 @@ def test_main_allows_import_of_shared_helper() -> None:
         {
             "tool_name": "Write",
             "tool_input": {
-                "file_path": "shared_utils/samsung_utils/cleanup.py",
+                "file_path": "shared_utils/vendor_utils/cleanup.py",
                 "content": (
                     "from shared_utils.web_automation.utils.windows_filesystem import "
                     "force_rmtree\n\nforce_rmtree(path)\n"

package/hooks/blocking/test_pii_scanner.py

@@ -24,7 +24,7 @@ SYNTHETIC_AWS_KEY = "AKIA" + ("B" * 16)
 SYNTHETIC_PEM_HEADER = "-----BEGIN RSA PRIVATE KEY-----"
 SYNTHETIC_REAL_EMAIL = "person.fixture@company-example.io"
 SYNTHETIC_SAFE_EMAIL = "user@example.com"
-SYNTHETIC_GITHUB_NOREPLY_EMAIL = "24366590+octocat@users.noreply.github.com"
+SYNTHETIC_GITHUB_NOREPLY_EMAIL = "81234567+octocat@users.noreply.github.com"
 SYNTHETIC_HOME_PATH = r"C:\Users\fixture_real_user\notes.txt"
 SYNTHETIC_PLACEHOLDER_HOME = r"C:\Users\<you>\notes.txt"
 SYNTHETIC_PRIVATE_IP = "192.168.42.17"

package/hooks/blocking/test_pytest_testpaths_orphan_blocker.py

@@ -20,7 +20,7 @@ HOOK_SCRIPT_PATH = HOOK_DIRECTORY / "pytest_testpaths_orphan_blocker.py"
 
 PYPROJECT_WITH_EXPLICIT_TESTPATHS = (
     "[tool.pytest.ini_options]\n"
-    'testpaths = [\n    "tests",\n    "samsung_utils/tests",\n]\n'
+    'testpaths = [\n    "tests",\n    "vendor_utils/tests",\n]\n'
     'python_files = ["test_*.py"]\n'
 )
 
@@ -91,7 +91,7 @@ def test_find_flags_test_directory_absent_from_explicit_testpaths(tmp_path: Path
 def test_find_passes_test_directory_listed_in_testpaths(tmp_path: Path) -> None:
     package_root = tmp_path / "shared_utils"
     _write_package(package_root, PYPROJECT_WITH_EXPLICIT_TESTPATHS)
-    registered_test_file = package_root / "samsung_utils" / "tests" / "test_normalizer.py"
+    registered_test_file = package_root / "vendor_utils" / "tests" / "test_normalizer.py"
     assert find_unregistered_test_directory(str(registered_test_file)) is None
 
 

package/hooks/git-hooks/conftest.py

@@ -28,3 +28,19 @@ for each_module_name in list(sys.modules):
     ):
         del sys.modules[each_module_name]
 importlib.invalidate_caches()
+
+
+import pytest
+
+from git_hooks_constants.verification_notice_constants import (
+    TARGET_REPOSITORY_ENVIRONMENT_VARIABLE,
+)
+
+EXAMPLE_TARGET_REPOSITORY = "example-owner/example-repo"
+
+
+@pytest.fixture(autouse=True)
+def configured_target_repository(monkeypatch: pytest.MonkeyPatch) -> str:
+    """Point the verification notice at the example repository for each test."""
+    monkeypatch.setenv(TARGET_REPOSITORY_ENVIRONMENT_VARIABLE, EXAMPLE_TARGET_REPOSITORY)
+    return EXAMPLE_TARGET_REPOSITORY

package/hooks/git-hooks/git_hooks_constants/verification_notice_constants.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 NOTICE_EVENT_COMMIT: str = "commit"
 NOTICE_EVENT_PUSH: str = "push"
 ALL_NOTICE_EVENTS: frozenset[str] = frozenset({NOTICE_EVENT_COMMIT, NOTICE_EVENT_PUSH})
-TARGET_REPOSITORY_REMOTE: str = "jonecho/python-automation"
+TARGET_REPOSITORY_ENVIRONMENT_VARIABLE: str = "CLAUDE_VERIFICATION_TARGET_REPOSITORY"
 GIT_CONFIG_SUBCOMMAND: str = "config"
 GIT_REV_PARSE_SUBCOMMAND: str = "rev-parse"
 ALL_GIT_REMOTE_URL_QUERY: tuple[str, ...] = (GIT_CONFIG_SUBCOMMAND, "--get", "remote.origin.url")

package/hooks/git-hooks/test_post_commit.py

@@ -27,7 +27,7 @@ def test_native_git_commit_notice_reports_the_new_head(tmp_path: Path) -> None:
     repository_path = create_native_repository(
         tmp_path,
         "repo",
-        "https://github.com/JonEcho/python-automation.git",
+        "https://github.com/example-owner/example-repo.git",
     )
     hook_directory = tmp_path / "hooks"
     install_native_hook(repository_path, hook_directory, "post-commit", "post_commit")

package/hooks/git-hooks/test_pre_commit.py

@@ -44,7 +44,7 @@ def test_native_git_commit_allows_missing_setup_and_prints_advisory(tmp_path: Pa
     repository_path.mkdir()
     configure_native_repository(
         repository_path,
-        "https://github.com/JonEcho/python-automation.git",
+        "https://github.com/example-owner/example-repo.git",
     )
     hook_directory = tmp_path / "hooks"
     install_native_hook(repository_path, hook_directory, "pre-commit", "pre_commit")

package/hooks/git-hooks/test_pre_push.py

@@ -44,7 +44,7 @@ def test_native_git_push_to_local_bare_remote_allows_missing_setup(tmp_path: Pat
     repository_path = create_native_repository(
         tmp_path,
         "repo",
-        "https://github.com/JonEcho/python-automation.git",
+        "https://github.com/example-owner/example-repo.git",
         initial_branch="main",
     )
     run_git(repository_path, "add", "README.md")
@@ -54,7 +54,7 @@ def test_native_git_push_to_local_bare_remote_allows_missing_setup(tmp_path: Pat
     configure_remote_url_rewrite(
         repository_path,
         bare_repository_path,
-        "https://github.com/JonEcho/python-automation.git",
+        "https://github.com/example-owner/example-repo.git",
     )
     hook_directory = tmp_path / "hooks"
     install_native_hook(repository_path, hook_directory, "pre-push", "pre_push")

package/hooks/git-hooks/test_verification_start.py

@@ -23,7 +23,7 @@ def build_context(
     repository_root: Path,
     *,
     event: str = "commit",
-    repository_remote: str = "jonecho/python-automation",
+    repository_remote: str = "example-owner/example-repo",
 ) -> VerificationNoticeContext:
     git_directory = repository_root / ".git"
     return VerificationNoticeContext(

package/hooks/git-hooks/verification_notice.py

@@ -35,7 +35,6 @@ from git_hooks_constants.verification_notice_constants import (
     PYTHON_COMMAND,
     REPORT_FILE_NAME,
     SCOPED_VERIFICATION_SCRIPT_PATH,
-    TARGET_REPOSITORY_REMOTE,
     UNKNOWN_SHA,
 )
 
@@ -49,6 +48,7 @@ from verification_notice_context import (
     VerificationNoticeContext,
     _load_notice_context,
     _run_git_query,
+    is_target_repository,
 )
 from verification_start import load_runner_configuration, start_automatic_advisory
 from verification_notice_state import (
@@ -71,7 +71,7 @@ def build_verification_notice(context: VerificationNoticeContext) -> str:
     Returns:
         The formatted advisory text, or an empty string for another repository.
     """
-    if context.repository_remote != TARGET_REPOSITORY_REMOTE:
+    if not is_target_repository(context.repository_remote):
         return ""
     current_head = context.current_head or UNKNOWN_SHA
     state, verified_head = _evaluate_context(context, _run_git_query)

package/hooks/git-hooks/verification_notice_context.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from collections.abc import Mapping
 from dataclasses import dataclass
@@ -32,7 +33,7 @@ from git_hooks_constants.verification_notice_constants import (
     REPOSITORY_PART_INDEX,
     SELECTED_MANIFEST_PATH_FIELD,
     SELECTION_FIELD,
-    TARGET_REPOSITORY_REMOTE,
+    TARGET_REPOSITORY_ENVIRONMENT_VARIABLE,
 )
 from local_verification.manifest import ManifestRunFatal, load_manifest
 
@@ -52,6 +53,24 @@ class VerificationNoticeContext:
     all_report_fields: Mapping[str, object] | None
 
 
+def is_target_repository(repository_remote: str | None) -> bool:
+    """Report whether a normalized remote names the configured target repository.
+
+    The target is read from the environment at call time and has no default,
+    so an unset or blank setting matches no repository.
+
+    Args:
+        repository_remote: The normalized owner/name remote, or None.
+
+    Returns:
+        True when the remote equals the configured target, case-insensitively.
+    """
+    configured_target = os.environ.get(TARGET_REPOSITORY_ENVIRONMENT_VARIABLE, "").strip()
+    if not configured_target or repository_remote is None:
+        return False
+    return repository_remote.casefold() == configured_target.casefold()
+
+
 def normalize_repository_remote(remote_url: str) -> str | None:
     """Return an owner/repository slug from common Git remote URL forms.
 
@@ -85,7 +104,7 @@ def _load_notice_context(
     normalized_remote = normalize_repository_remote(
         _run_git_query(repository_root, ALL_GIT_REMOTE_URL_QUERY, False) or ""
     )
-    if normalized_remote != TARGET_REPOSITORY_REMOTE or current_head is None:
+    if not is_target_repository(normalized_remote) or current_head is None:
         return None
     if not git_directory_text:
         return None

package/hooks/git-hooks/verification_start.py

@@ -20,9 +20,8 @@ from git_hooks_constants.verification_notice_constants import (
     RUNNER_FILE_NAME,
     RUNNER_PYTHON_FIELD,
     RUNNER_SETTINGS_FIELD,
-    TARGET_REPOSITORY_REMOTE,
 )
-from verification_notice_context import VerificationNoticeContext
+from verification_notice_context import VerificationNoticeContext, is_target_repository
 
 _subprocess_window_hooks_directory = str(Path(__file__).resolve().parents[2] / "hooks")
 if _subprocess_window_hooks_directory not in sys.path:
@@ -33,7 +32,7 @@ from hooks_constants.subprocess_window import hidden_window_creation_flags
 
 def start_automatic_advisory(context: VerificationNoticeContext) -> None:
     """Start the detached advisory poller when native metadata is valid."""
-    if context.repository_remote != TARGET_REPOSITORY_REMOTE:
+    if not is_target_repository(context.repository_remote):
         return
     if context.event not in ALL_NOTICE_EVENTS:
         return

package/package.json

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

package/rules/durable-post-artifacts.md

@@ -67,9 +67,10 @@ server write. Pass the matching action and body file. Use `pr-create`,
 
 Pass `--repository <owner>/<name>` for the repository the post targets. A
 post may name a private organization only inside a repository that
-organization owns. The linter holds the names as digests, so it reports the
-line that names one without printing the name. Describe the organization in
-general terms and drop the link.
+organization owns. The same digests cover the owner's private repository, the
+owner's personal handle, and a private client. The linter holds the names as
+digests, so it reports the line that names one without printing the name.
+Describe the name in general terms and drop the link.
 
 The linter reads the body file and reports a volatile local path without
 printing the body. Fix the body and rerun the linter before posting.

package/scripts/claude_account_profile.py

@@ -31,6 +31,7 @@ import json
 import os
 import subprocess
 import sys
+from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -214,11 +215,11 @@ def _unlink_orphaned_links(main_home: Path, profile_home: Path) -> tuple[str, ..
 
 
 def _unlink_local_names_linked_to_main(
-    main_home: Path, profile_home: Path
+    main_home: Path, profile_home: Path, is_local: Callable[[str], bool]
 ) -> tuple[str, ...]:
     all_unlinked: list[str] = []
     for each_entry in sorted(profile_home.iterdir()):
-        if not is_account_local(each_entry.name):
+        if not is_local(each_entry.name):
             continue
         if not links_to(each_entry, main_home / each_entry.name):
             continue
@@ -237,13 +238,16 @@ def _clear_entry(entry_path: Path, source_path: Path, replaced_directory: Path)
 
 
 def _link_shared_entries(
-    main_home: Path, profile_home: Path, replaced_directory: Path
+    main_home: Path,
+    profile_home: Path,
+    replaced_directory: Path,
+    is_local: Callable[[str], bool],
 ) -> tuple[tuple[str, ...], tuple[str, ...]]:
     all_linked: list[str] = []
     all_moved_aside: list[str] = []
     for each_source in sorted(main_home.iterdir()):
         entry_path = profile_home / each_source.name
-        if is_account_local(each_source.name) or links_to(entry_path, each_source):
+        if is_local(each_source.name) or links_to(entry_path, each_source):
             continue
         if os.path.lexists(entry_path) and _clear_entry(
             entry_path, each_source, replaced_directory
@@ -255,14 +259,19 @@ def _link_shared_entries(
 
 
 def sync_profile(
-    *, main_home: Path, profile_home: Path, now: datetime
+    *,
+    main_home: Path,
+    profile_home: Path,
+    now: datetime,
+    is_local: Callable[[str], bool] = is_account_local,
 ) -> ProfileSyncReport:
     """Link every shared main-home entry into the profile home.
 
     Args:
-        main_home: The main account's Claude home.
-        profile_home: The second account's Claude home.
+        main_home: The main account's home.
+        profile_home: The profile account's home.
         now: The run time that names the folder stale entries move into.
+        is_local: Tells whether a top-level entry belongs to one account only.
 
     Returns:
         The entries the run linked, moved aside, and unlinked.
@@ -271,11 +280,14 @@ def sync_profile(
     all_unlinked = tuple(
         sorted(
             _unlink_orphaned_links(main_home, profile_home)
-            + _unlink_local_names_linked_to_main(main_home, profile_home)
+            + _unlink_local_names_linked_to_main(main_home, profile_home, is_local)
         )
     )
     all_linked, all_moved_aside = _link_shared_entries(
-        main_home, profile_home, profile_home / REPLACED_DIRECTORY_NAME / _stamp(now)
+        main_home,
+        profile_home,
+        profile_home / REPLACED_DIRECTORY_NAME / _stamp(now),
+        is_local,
     )
     return ProfileSyncReport(
         all_linked=all_linked,