claude-dev-env 8.7.0 → 8.8.0

package/.agents/skills/team-advisor/SKILL.md

@@ -25,7 +25,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default low) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
-3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path, pass `flags: ["--advisor"]` with Astra.
+3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path and the spawn tool has a `flags` field, pass `flags: ["--advisor"]` with Astra and record `advisor_flag: passed`. A spawn that skips an offered flag is a failed bind. When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `advisor_flag: unavailable`, and treat it as bound.
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
@@ -49,7 +49,7 @@ Aim for two consults on a normal task: one after orientation and one after write
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.
 - Keep an optional reference gap in the reference record: path, status, repair action, and repair result. A reference gap leaves bind status separate.
-- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`.
+- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`, plus `advisor_flag: passed` or `advisor_flag: unavailable`.
 - Mark `fallback_kind: broken` only when the selected bind or reply path fails. Record the selected tier, fallback reason, and reply path in the same evidence object.
 - Record first, recovery, and completion consults with changed evidence, validation, unresolved risks, and report-back status.
 - Write the evidence object to the session-controlled `model-tier-run.json` record described in `advisor-tool.md`.

package/_shared/advisor/reference/identity.md

@@ -19,7 +19,7 @@ When both `codex` and `claude` tokens appear, Codex wins. Empty text is ThirdPar
 
 **Claude.** Spawn `subagent_type: session-advisor` at Fable through the Agent tool. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 
-**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind. Do not walk Fable on a Codex host.
+**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`. When it has none, as in `codex exec`, spawn `gpt-6-astra` plainly and record `fallback.advisor_flag: "unavailable"`. Both count as a bind. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind, or when the spawn skips a flag the host offers. Do not walk Fable on a Codex host.
 
 **ThirdParty.** Bind Fable through the CLI Claude-chain. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 

package/_shared/advisor/reference/spawn-walk-log.md

@@ -29,5 +29,5 @@ Exit code `1` means a ladder invariant failed.
 Exit code `2` means the path or JSON was unusable.
 The same checks are available in-process via `validate_model_tier_run(run)`.
 
-The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"`.
+The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"` and `advisor_flag: "passed"` or `advisor_flag: "unavailable"`. A missing `advisor_flag` or `advisor_flag: "omitted"` fails validation.
 Host policy sits on top of it. See the Model floor section of the protocol.

package/_shared/advisor/reference/warm-up.md

@@ -31,7 +31,9 @@ The agent finishes its first turn standing by. `SendMessage` alone resumes it; b
 ## Codex host
 
 Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`) with the charter as its prompt.
-Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind.
+When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`.
+When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `fallback.advisor_flag: "unavailable"`, and treat the advisor as bound.
+Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind, or when it skips a flag the host offers.
 The `ADVISOR_ASTRA` flag is not required. Do not walk Fable. Consults stay in-session with that Astra subagent.
 Identity routing: [`identity.md`](identity.md).
 

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -106,3 +106,18 @@ ALL_ADVISOR_REPLY_PATHS: frozenset[str] = frozenset(
     {"native", "sendmessage", "cli", "codex", "none"}
 )
 EVIDENCE_MUST_BE_OBJECT_MESSAGE: str = "evidence must be an object"
+ADVISOR_FLAG_PASSED: str = "passed"
+ADVISOR_FLAG_UNAVAILABLE: str = "unavailable"
+ADVISOR_FLAG_OMITTED: str = "omitted"
+ALL_ADVISOR_FLAG_STATES: frozenset[str] = frozenset(
+    {ADVISOR_FLAG_PASSED, ADVISOR_FLAG_UNAVAILABLE, ADVISOR_FLAG_OMITTED}
+)
+UNKNOWN_ADVISOR_FLAG_MESSAGE: str = (
+    "evidence.fallback.advisor_flag must be passed, unavailable, or omitted"
+)
+MISSING_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra success requires evidence.fallback.advisor_flag"
+)
+OMITTED_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra spawn skipped the --advisor flag the host offers"
+)

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -67,6 +67,8 @@ from advisor_scripts_constants.astra_advisor_constants import (
     ASTRA_FALLBACK_KIND_DECLINED,
 )
 from advisor_scripts_constants.model_tier_run_validator_constants import (
+    ADVISOR_FLAG_OMITTED,
+    ALL_ADVISOR_FLAG_STATES,
     ALL_ADVISOR_REPLY_PATHS,
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
@@ -82,10 +84,13 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (
     HOST_PROFILE_JSON_KEY,
     HOST_PROFILE_MUST_BE_STRING_MESSAGE,
     INCOMPLETE_FALLBACK_WALK_MESSAGE,
+    MISSING_ADVISOR_FLAG_MESSAGE,
     MISSING_FALLBACK_REASON_MESSAGE,
+    OMITTED_ADVISOR_FLAG_MESSAGE,
     SELECTED_TIER_MISMATCH_MESSAGE,
     SELECTED_TIER_NOT_NULL_MESSAGE,
     THIRD_PARTY_MODEL_TIER,
+    UNKNOWN_ADVISOR_FLAG_MESSAGE,
     UNKNOWN_HOST_PROFILE_ERROR,
     UNKNOWN_OWN_TIER_MESSAGE,
 )
@@ -212,14 +217,26 @@ def _validate_fallback_reply_path(
         raise ModelTierRunError(
             "evidence.fallback.reply_path is not a known advisor path"
         )
-    if (
+    is_codex_astra_success = (
         canonical_host_profile(run.host_profile) == HOST_PROFILE_CODEX
         and maybe_run_selected_tier == ADVISOR_MODEL_TIER
-        and reply_path != "native"
-    ):
+    )
+    if is_codex_astra_success and reply_path != "native":
         raise ModelTierRunError(
             "Codex Astra success requires the native reply path"
         )
+    raw_advisor_flag = fallback_by_name.get("advisor_flag")
+    if raw_advisor_flag is None:
+        if is_codex_astra_success:
+            raise ModelTierRunError(MISSING_ADVISOR_FLAG_MESSAGE)
+        return
+    if (
+        not isinstance(raw_advisor_flag, str)
+        or raw_advisor_flag not in ALL_ADVISOR_FLAG_STATES
+    ):
+        raise ModelTierRunError(UNKNOWN_ADVISOR_FLAG_MESSAGE)
+    if is_codex_astra_success and raw_advisor_flag == ADVISOR_FLAG_OMITTED:
+        raise ModelTierRunError(OMITTED_ADVISOR_FLAG_MESSAGE)
 
 
 def _validate_fallback_evidence(

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -44,7 +44,16 @@ def _native_codex_evidence(
     *,
     reply_path: str = "native",
     reference_status: str = "missing",
+    advisor_flag: str | None = "passed",
 ) -> dict[str, object]:
+    fallback: dict[str, object] = {
+        "selected_tier": "Astra",
+        "fallback_kind": None,
+        "fallback_reason": None,
+        "reply_path": reply_path,
+    }
+    if advisor_flag is not None:
+        fallback["advisor_flag"] = advisor_flag
     return {
         "schema_version": 1,
         "reference": {
@@ -53,12 +62,7 @@ def _native_codex_evidence(
             "repair_action": "use the projected docs root",
             "repair_result": "read",
         },
-        "fallback": {
-            "selected_tier": "Astra",
-            "fallback_kind": None,
-            "fallback_reason": None,
-            "reply_path": reply_path,
-        },
+        "fallback": fallback,
         "consult": {
             "changed_evidence": ["native bind returned a reply"],
             "validation": ["signal and session id read back"],
@@ -96,6 +100,46 @@ def test_codex_native_success_rejects_non_native_reply_path() -> None:
         validate_model_tier_run(run)
 
 
+def _codex_astra_success_run(evidence: dict[str, object]) -> ModelTierRun:
+    return ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=evidence,
+    )
+
+
+def test_codex_plain_astra_spawn_binds_when_host_lacks_advisor_flag() -> None:
+    run = _codex_astra_success_run(
+        _native_codex_evidence(advisor_flag="unavailable")
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_codex_astra_spawn_that_skips_offered_advisor_flag_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="omitted"))
+
+    with pytest.raises(ModelTierRunError, match="--advisor"):
+        validate_model_tier_run(run)
+
+
+def test_codex_astra_success_without_advisor_flag_record_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag=None))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
+def test_unknown_advisor_flag_state_is_rejected() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="skipped"))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
 def test_broken_bind_keeps_fallback_evidence_separate_from_reference_gap() -> None:
     evidence = _native_codex_evidence()
     evidence["fallback"] = {

package/docs/references/advisor-tool.md

@@ -40,7 +40,7 @@ Work a disagreement in this order: keep the observed evidence in the record, nam
 
 ## Recovery record
 
-Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"` and `reply_path: "native"`.
+Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"`, `reply_path: "native"`, and `advisor_flag`. The value is `"passed"` when the spawn tool offers the `--advisor` flag and the spawn passed it, or `"unavailable"` when the spawn tool has no flag field. `"omitted"` fails the bind.
 
 ```json
 {
@@ -56,7 +56,8 @@ Keep one versioned `evidence` object in the session-controlled `model-tier-run.j
       "selected_tier": "Astra",
       "fallback_kind": null,
       "fallback_reason": null,
-      "reply_path": "native"
+      "reply_path": "native",
+      "advisor_flag": "passed"
     },
     "consult": {
       "changed_evidence": ["native bind returned a reply"],

package/docs/second-claude-account.md

@@ -0,0 +1,50 @@
+# Second Claude account
+
+A second Claude subscription runs agents on the same machine as the main one. It
+shares every skill, rule, plugin, setting and doc in the main Claude home, and it
+keeps its own sign-in and history.
+
+## Pieces
+
+| File | What it does |
+|---|---|
+| `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
+| `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
+| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
+
+The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to
+`claude`, so `claude-ev -p "..."` runs like `claude -p "..."` on the second
+account.
+
+These entries stay per account and are never linked: `.credentials.json` and
+`.claude.json` with their backups, `projects`, `sessions`, `todos`, `history.jsonl`,
+and the other state folders named in the constants file.
+
+## Sign in once
+
+```
+python packages/claude-dev-env/scripts/claude_account_profile.py
+claude-ev auth login
+```
+
+The sign-in lives in `~/.claude-profiles/ev/.credentials.json` on that machine.
+Claude refreshes it on each run.
+
+## Which account a job uses
+
+The main account belongs to the person who works on it, so a job borrows it only
+to spend leftover usage that expires soon.
+
+| Condition | Account |
+|---|---|
+| Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
+| Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
+| Second meter unreadable | second, whose own run refreshes the sign-in |
+| Otherwise | wait, with the next reset time |
+
+An unreadable main meter never picks main.
+
+```
+python packages/claude-dev-env/scripts/claude_account_choice.py
+{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "..."}
+```

package/hooks/blocking/test_pii_scanner.py

@@ -24,6 +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_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"
@@ -42,6 +43,13 @@ def test_flags_real_email_and_allows_example_domain() -> None:
     assert all_safe_hits == []
 
 
+def test_allows_github_noreply_email_and_still_flags_a_company_lookalike() -> None:
+    all_noreply_hits = scan_text_for_pii(f"commit author {SYNTHETIC_GITHUB_NOREPLY_EMAIL}")
+    all_lookalike_hits = scan_text_for_pii("contact person@users.noreply.github.com.evil.io")
+    assert all_noreply_hits == []
+    assert any(each.category == "email" for each in all_lookalike_hits)
+
+
 def test_flags_home_path_and_allows_placeholder_user() -> None:
     all_home_hits = scan_text_for_pii(f"path is {SYNTHETIC_HOME_PATH}")
     all_placeholder_hits = scan_text_for_pii(f"path is {SYNTHETIC_PLACEHOLDER_HOME}")

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -136,6 +136,7 @@ ALL_SAFE_EMAIL_DOMAINS: frozenset[str] = frozenset(
         "test",
         "local",
         "test.local",
+        "users.noreply.github.com",
     }
 )
 

package/package.json

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

package/rules/long-horizon-autonomy.md

@@ -18,6 +18,17 @@ A pause is a request you deliver, not a state you enter. Put it in the channel t
 
 Before you end any turn, read your last paragraph. If it is a plan, an analysis, a list of next steps, or a statement of intent ("I'll run the tests", "next I'll wire it up"), do that work with tool calls before you stop. End the turn only when the task is done or you are blocked on input only the user can give.
 
+Four turn endings leave owed work unstarted. Each one is a stop to remove:
+
+- A summary of the work so far that closes by naming the next step, with no tool call to start it.
+- An offer to continue unless the user objects.
+- A list of decisions for the user when none of them blocks the remaining work.
+- A pause chosen because the turn ran long or a milestone finished.
+
+A status note or a recommendation on an open decision rides in the same message as the next tool call. The stops that stay are the two where nothing can move: the next step needs the user, or the blocker is a control that is protected from you on purpose. Confirmation before a risky or destructive action still applies.
+
+A harness or routine that drives an unattended run reads a turn that ends in text as a report. When open checklist items remain and the turn names no blocker, it sends one short message naming those items. It stops after two or three such continuations on one task, so a stuck run ends where a reader can review it. [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#unattended-agentic-runs) is the source for this list and this loop.
+
 In an autonomous pipeline the user cannot answer mid-task. For reversible actions that follow from the original request, act without asking; save any follow-up offers for after the task is done.
 
 Authority the task already granted stays granted. A later preference about tone, brevity, or reply format changes how you report, never what you are allowed to do. Re-asking for permission the task already gave hands the work back to the user, who then does it by hand.

package/scripts/claude_account_choice.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Name the Claude account a runner job uses, protecting the main account.
+
+The main account is the one its owner works on, so a job borrows it only to
+spend leftover usage that expires soon. Every other job goes to the second
+account while that account has room, and waits when it has none::
+
+    main week resets in 5 hours, 20% left, 5-hour window 10% used -> main
+    main week resets in 3 days                                    -> second
+    second at 99% of its week, main not spendable                 -> wait
+    main meter unread                                             -> never main
+
+::
+
+    python claude_account_choice.py --main-config-dir C:/Users/me/.claude
+        --second-config-dir C:/Users/me/.claude-profiles/ev
+    {"account": "second", "config_dir": "C:/Users/me/.claude-profiles/ev",
+     "reason": "second account has 60% of its week and 90% of its 5-hour window left"}
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from claude_account_profile import default_profile_home
+from claude_chain_usage import (
+    AccountUsageMeters,
+    WeeklyUtilizationProbeError,
+    probe_account_meters,
+)
+from dev_env_scripts_constants.claude_account_constants import (
+    CHOICE_MAIN,
+    CHOICE_SECOND,
+    CHOICE_WAIT,
+    CREDENTIALS_FILE_NAME,
+    FULL_PERCENT,
+    JSON_ACCOUNT_KEY,
+    JSON_CONFIG_DIRECTORY_KEY,
+    JSON_REASON_KEY,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+    MAIN_SESSION_USED_CEILING_PERCENT,
+    MAIN_SPEND_WINDOW,
+    MAIN_WEEKLY_USED_CEILING_PERCENT,
+    REASON_MAIN_EXPIRING_TEMPLATE,
+    REASON_SECOND_HAS_ROOM_TEMPLATE,
+    REASON_SECOND_UNREAD,
+    REASON_WAIT_TEMPLATE,
+    SECOND_SESSION_USED_CEILING_PERCENT,
+    SECOND_WEEKLY_USED_CEILING_PERCENT,
+    SECONDS_PER_HOUR,
+    UNKNOWN_RESET_TEXT,
+)
+
+
+@dataclass(frozen=True)
+class AccountDecision:
+    """The account a job runs on, and the plain-words reason for it."""
+
+    account: str
+    reason: str
+
+
+def _main_spendable_reason(
+    main_meters: AccountUsageMeters | None, now: datetime
+) -> str | None:
+    if main_meters is None:
+        return None
+    session_used = main_meters.session_utilization
+    weekly_used = main_meters.weekly_utilization
+    weekly_resets_at = main_meters.weekly_resets_at
+    if session_used is None or weekly_used is None or weekly_resets_at is None:
+        return None
+    time_until_reset = weekly_resets_at - now
+    is_expiring_soon = time_until_reset <= MAIN_SPEND_WINDOW
+    has_weekly_room = weekly_used < MAIN_WEEKLY_USED_CEILING_PERCENT
+    has_session_room = session_used < MAIN_SESSION_USED_CEILING_PERCENT
+    if not (is_expiring_soon and has_weekly_room and has_session_room):
+        return None
+    return REASON_MAIN_EXPIRING_TEMPLATE.format(
+        hours_until_reset=int(time_until_reset.total_seconds() // SECONDS_PER_HOUR),
+        remaining_percent=FULL_PERCENT - weekly_used,
+    )
+
+
+def _wait_decision(
+    second_meters: AccountUsageMeters, *, is_week_blocked: bool
+) -> AccountDecision:
+    blocking_reset = (
+        second_meters.weekly_resets_at
+        if is_week_blocked
+        else second_meters.session_resets_at
+    )
+    return AccountDecision(
+        account=CHOICE_WAIT,
+        reason=REASON_WAIT_TEMPLATE.format(
+            weekly_used_percent=second_meters.weekly_utilization,
+            session_used_percent=second_meters.session_utilization,
+            next_reset=(
+                blocking_reset.isoformat() if blocking_reset else UNKNOWN_RESET_TEXT
+            ),
+        ),
+    )
+
+
+def _second_account_decision(
+    second_meters: AccountUsageMeters | None,
+) -> AccountDecision:
+    if second_meters is None:
+        return AccountDecision(account=CHOICE_SECOND, reason=REASON_SECOND_UNREAD)
+    session_used = second_meters.session_utilization
+    weekly_used = second_meters.weekly_utilization
+    if session_used is None or weekly_used is None:
+        return AccountDecision(account=CHOICE_SECOND, reason=REASON_SECOND_UNREAD)
+    is_week_blocked = weekly_used >= SECOND_WEEKLY_USED_CEILING_PERCENT
+    is_session_blocked = session_used >= SECOND_SESSION_USED_CEILING_PERCENT
+    if is_week_blocked or is_session_blocked:
+        return _wait_decision(second_meters, is_week_blocked=is_week_blocked)
+    return AccountDecision(
+        account=CHOICE_SECOND,
+        reason=REASON_SECOND_HAS_ROOM_TEMPLATE.format(
+            weekly_remaining_percent=FULL_PERCENT - weekly_used,
+            session_remaining_percent=FULL_PERCENT - session_used,
+        ),
+    )
+
+
+def choose_account(
+    *,
+    main_meters: AccountUsageMeters | None,
+    second_meters: AccountUsageMeters | None,
+    now: datetime,
+) -> AccountDecision:
+    """Pick the account a job runs on from both accounts' meters.
+
+    ::
+
+        main: week resets in 5h, 80% used, 5-hour 10% used   -> main
+        main: week resets in 30h                             -> second, if it has room
+        main unread, second at 99% of its week               -> wait
+        main unread, second unread                           -> second
+
+    Main runs a job only to spend leftover usage that expires soon.
+
+    Args:
+        main_meters: The main account's meters, or None when unread.
+        second_meters: The second account's meters, or None when unread.
+        now: The time the reset windows are measured from.
+
+    Returns:
+        The chosen account and the reason.
+    """
+    main_reason = _main_spendable_reason(main_meters, now)
+    if main_reason is not None:
+        return AccountDecision(account=CHOICE_MAIN, reason=main_reason)
+    return _second_account_decision(second_meters)
+
+
+def read_account_meters(credentials_path: Path) -> AccountUsageMeters | None:
+    """Read one account's meters, or None when its credential or probe fails.
+
+    Args:
+        credentials_path: The account's CLI credential file.
+
+    Returns:
+        The meters, or None when they cannot be read.
+    """
+    try:
+        return probe_account_meters(credentials_path)
+    except WeeklyUtilizationProbeError:
+        return None
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Name the Claude account a runner job uses."
+    )
+    parser.add_argument(
+        "--main-config-dir",
+        type=Path,
+        default=Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+    )
+    parser.add_argument(
+        "--second-config-dir",
+        type=Path,
+        default=default_profile_home(),
+    )
+    return parser
+
+
+def decision_payload(
+    decision: AccountDecision, *, config_directory: Path | None
+) -> dict[str, str | None]:
+    """Shape a decision as the JSON object the runner job reads.
+
+    ::
+
+        AccountDecision("second", "...") with the profile directory
+        -> {"account": "second", "config_dir": "<profile>", "reason": "..."}
+
+    Args:
+        decision: The chosen account and reason.
+        config_directory: The Claude home the account runs under, or None on wait.
+
+    Returns:
+        The account, its Claude home, and the reason.
+    """
+    return {
+        JSON_ACCOUNT_KEY: decision.account,
+        JSON_CONFIG_DIRECTORY_KEY: str(config_directory) if config_directory else None,
+        JSON_REASON_KEY: decision.reason,
+    }
+
+
+def main(all_command_arguments: list[str]) -> int:
+    """Print the chosen account as JSON.
+
+    Args:
+        all_command_arguments: Command-line arguments after the program name.
+
+    Returns:
+        Zero once the choice is printed.
+    """
+    arguments = _build_argument_parser().parse_args(all_command_arguments)
+    config_directory_by_account = {
+        CHOICE_MAIN: arguments.main_config_dir,
+        CHOICE_SECOND: arguments.second_config_dir,
+    }
+    decision = choose_account(
+        main_meters=read_account_meters(arguments.main_config_dir / CREDENTIALS_FILE_NAME),
+        second_meters=read_account_meters(
+            arguments.second_config_dir / CREDENTIALS_FILE_NAME
+        ),
+        now=datetime.now().astimezone(),
+    )
+    config_directory = config_directory_by_account.get(decision.account)
+    print(json.dumps(decision_payload(decision, config_directory=config_directory)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))