claude-dev-env 2.11.0 → 2.12.0

package/_shared/advisor/reference/sol-rung.md

@@ -5,8 +5,11 @@ Open this when `ADVISOR_SOL_XHIGH` is set and a bind is starting.
 
 ## Flag
 
-`ADVISOR_SOL_XHIGH=1` (or `true` / `yes` / `on`) opens the rung, set in the environment or by the consuming skill's invocation.
-Flag off: the walk starts at the host's Claude ladder, Fable first.
+`ADVISOR_SOL_XHIGH=1` (or `true` / `yes` / `on`) opens the rung. Two channels exist: set the variable in the helper's process environment, or pass `--enable-sol` on the helper invocation — the CLI flag opens the rung for that run without touching the environment.
+Flag off both ways: the walk starts at the host's Claude ladder, Fable first.
+A Windows `setx` write only updates the persisted user environment; only a process started after that write inherits the new value, so an already-running session either sets the flag in its own invoking process environment or passes `--enable-sol`.
+
+Every fallback reply carries a `fallback_kind` field: `declined` when policy closed the rung (flag off, usage meter at or below the gate) and `broken` when the Sol path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report, not a routing outcome.
 
 ## Preflight
 

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

@@ -25,6 +25,7 @@ State plainly:
 - Reply via SendMessage to whoever sent the consult, by name — each reply goes back to its own sender, and many different consumers may reach this one agent.
 - Treat each consult on its own terms, keyed to the sender's stated assignment. Different consumers' consults will interleave in this one transcript — keep each consumer's context separate, and blend only when a consult explicitly asks for that.
 - If a consult re-raises a question already answered, with nothing new attached, reply by restating the prior answer and naming it as a restatement.
+- Every reply, including this first bind turn, opens its first line with exactly one of the four uppercase signal words — `ENDORSE`, `CORRECTION`, `PLAN`, `STOP` — and nothing else on that line. Standing by after the bind is itself an `ENDORSE` of the charter, stated as that first line.
 
 The agent finishes its first turn standing by. `SendMessage` alone resumes it; between consults it waits quietly.
 

package/_shared/advisor/scripts/codex_sol_advisor.py

@@ -7,6 +7,7 @@ import importlib
 import json
 import math
 import os
+import shutil
 import subprocess
 import sys
 from collections.abc import Callable, Mapping, Sequence
@@ -20,6 +21,7 @@ if _config_directory_text not in sys.path:
     sys.path.insert(0, _config_directory_text)
 
 from advisor_scripts_constants.sol_advisor_constants import (  # noqa: E402
+    ADVISOR_CODEX_EXECUTABLE_ENV_VAR,
     CODEX_CONFIG_FLAG,
     CODEX_EXECUTABLE,
     CODEX_EXEC_SUBCOMMAND,
@@ -35,6 +37,10 @@ from advisor_scripts_constants.sol_advisor_constants import (  # noqa: E402
     SOL_CODEX_TIMEOUT_REASON,
     SOL_CODEX_TIMEOUT_SECONDS,
     SOL_ENV_VAR,
+    SOL_ENABLE_FLAG,
+    SOL_EXECUTABLE_NOT_FOUND_REASON,
+    SOL_FALLBACK_KIND_BROKEN,
+    SOL_FALLBACK_KIND_DECLINED,
     SOL_INVALID_SIGNAL_REASON,
     SOL_MALFORMED_JSONL_REASON,
     SOL_MISSING_SESSION_REASON,
@@ -63,6 +69,7 @@ class SolPreflight:
     eligible: bool
     percent_left: float | None
     reason: str
+    fallback_kind: str | None = None
 
 
 @dataclass(frozen=True)
@@ -78,17 +85,21 @@ class CodexSolAdvisorReply:
     sol_enabled: bool
     selected_tier: str
     outcome: str
+    fallback_kind: str | None
 
 
 def _preflight_fallback(
-    reason: str, percent_left: float | None
+    reason: str,
+    percent_left: float | None,
+    fallback_kind: str = SOL_FALLBACK_KIND_BROKEN,
 ) -> SolPreflight:
-    return SolPreflight(False, percent_left, reason)
+    return SolPreflight(False, percent_left, reason, fallback_kind)
 
 
 def _reply_fallback(
     reason: str,
     is_sol_enabled: bool,
+    fallback_kind: str | None = SOL_FALLBACK_KIND_BROKEN,
 ) -> CodexSolAdvisorReply:
     return CodexSolAdvisorReply(
         session_id=None,
@@ -100,6 +111,7 @@ def _reply_fallback(
         sol_enabled=is_sol_enabled,
         selected_tier=ADVISOR_FALLBACK_TIER,
         outcome=ADVISOR_FALLBACK_RESULT,
+        fallback_kind=fallback_kind,
     )
 
 
@@ -118,9 +130,16 @@ def _reply_success(
         sol_enabled=True,
         selected_tier=ADVISOR_MODEL_TIER,
         outcome=CODEX_BIND_SUCCESS_TOKEN,
+        fallback_kind=None,
     )
 
 
+def _resolved_setting_by_name(
+    setting_by_name: Mapping[str, str] | None,
+) -> Mapping[str, str]:
+    return os.environ if setting_by_name is None else setting_by_name
+
+
 def is_sol_advisor_enabled(
     setting_by_name: Mapping[str, str] | None,
 ) -> bool:
@@ -132,7 +151,7 @@ def is_sol_advisor_enabled(
     Returns:
         Whether the Sol feature flag contains a recognized truthy value.
     """
-    resolved_setting_by_name = os.environ if setting_by_name is None else setting_by_name
+    resolved_setting_by_name = _resolved_setting_by_name(setting_by_name)
     return (
         resolved_setting_by_name.get(SOL_ENV_VAR, "").strip().lower()
         in ALL_SOL_TRUTHY_VALUES
@@ -223,11 +242,11 @@ def run_sol_preflight(
             return _preflight_fallback(
                 f"{SOL_PREFLIGHT_FAILURE_REASON}: usage meter is unknown", None
             )
-        usage_gate = _load_usage_gate(probe_path)
         if not usage_gate(percent_left):
             return _preflight_fallback(
                 f"{SOL_PREFLIGHT_FAILURE_REASON}: usage meter is at or below the gate",
                 percent_left,
+                fallback_kind=SOL_FALLBACK_KIND_DECLINED,
             )
     except subprocess.TimeoutExpired as probe_error:
         return _preflight_fallback(f"{SOL_PROBE_TIMEOUT_REASON}: {probe_error}", None)
@@ -245,17 +264,44 @@ def run_sol_preflight(
     return SolPreflight(True, percent_left, "usage meter is above the Sol gate")
 
 
-def build_codex_arguments(session_id: str | None = None) -> list[str]:
+def resolve_codex_executable(
+    setting_by_name: Mapping[str, str] | None,
+) -> str | None:
+    """Resolve the Codex CLI executable to an invocable name or path.
+
+    A bare "codex" name fails Windows `CreateProcess`, since the npm shim
+    directory holds only `codex` (a sh script), `codex.cmd`, and `codex.ps1`.
+    `shutil.which` finds `codex.cmd` via `PATHEXT`. An explicit override
+    always wins and is trusted without a `which` check.
+
+    Args:
+        setting_by_name: Optional environment-like settings mapping.
+
+    Returns:
+        An invocable executable name or path, or None when unresolved.
+    """
+    resolved_setting_by_name = _resolved_setting_by_name(setting_by_name)
+    executable_override = resolved_setting_by_name.get(ADVISOR_CODEX_EXECUTABLE_ENV_VAR, "").strip()
+    if executable_override:
+        return executable_override
+    return shutil.which(CODEX_EXECUTABLE)
+
+
+def build_codex_arguments(
+    codex_executable: str,
+    session_id: str | None = None,
+) -> list[str]:
     """Build the installed CLI's shell-free bind or resume argv.
 
     Args:
+        codex_executable: Resolved executable name or path to invoke.
         session_id: Optional existing session to resume.
 
     Returns:
         The shell-free Codex command argument vector.
     """
     command_arguments = [
-        CODEX_EXECUTABLE,
+        codex_executable,
         CODEX_EXEC_SUBCOMMAND,
         CODEX_MODEL_FLAG,
         ADVISOR_CODEX_MODEL_ID,
@@ -333,6 +379,21 @@ def parse_codex_jsonl_reply(
     return _reply_success(discovered_session_id, final_guidance, guidance_signal)
 
 
+def _resolve_sol_preflight(
+    preflight: SolPreflight | None,
+    probe_path: Path | None,
+    process_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> SolPreflight:
+    if preflight is not None:
+        return preflight
+    resolved_probe_path = (
+        resolve_usage_probe_path(Path.home()) if probe_path is None else probe_path
+    )
+    return run_sol_preflight(
+        probe_path=resolved_probe_path, process_runner=process_runner
+    )
+
+
 def run_codex_sol_advisor(
     prompt: str,
     working_directory: Path,
@@ -356,26 +417,25 @@ def run_codex_sol_advisor(
     Returns:
         The parsed Sol guidance or an explicit Fable fallback reply.
     """
-    is_sol_enabled = is_sol_advisor_enabled(setting_by_name)
-    if not is_sol_enabled:
-        return _reply_fallback("Sol advisor flag is disabled", False)
-    resolved_preflight = (
-        run_sol_preflight(
-            probe_path=(
-                resolve_usage_probe_path(Path.home())
-                if probe_path is None
-                else probe_path
-            ),
-            process_runner=process_runner,
+    if not is_sol_advisor_enabled(setting_by_name):
+        return _reply_fallback(
+            "Sol advisor flag is disabled",
+            False,
+            fallback_kind=SOL_FALLBACK_KIND_DECLINED,
         )
-        if preflight is None
-        else preflight
-    )
+    codex_executable = resolve_codex_executable(setting_by_name)
+    if codex_executable is None:
+        return _reply_fallback(SOL_EXECUTABLE_NOT_FOUND_REASON, True)
+    resolved_preflight = _resolve_sol_preflight(preflight, probe_path, process_runner)
     if not resolved_preflight.eligible:
-        return _reply_fallback(resolved_preflight.reason, is_sol_enabled)
+        return _reply_fallback(
+            resolved_preflight.reason,
+            True,
+            fallback_kind=resolved_preflight.fallback_kind,
+        )
     try:
         completed_process = process_runner(
-            build_codex_arguments(session_id=session_id),
+            build_codex_arguments(codex_executable, session_id=session_id),
             cwd=str(working_directory),
             input=prompt,
             capture_output=True,
@@ -385,22 +445,18 @@ def run_codex_sol_advisor(
             timeout=SOL_CODEX_TIMEOUT_SECONDS,
         )
     except subprocess.TimeoutExpired as bind_error:
-        return _reply_fallback(
-            f"{SOL_CODEX_TIMEOUT_REASON}: {bind_error}", is_sol_enabled
-        )
+        return _reply_fallback(f"{SOL_CODEX_TIMEOUT_REASON}: {bind_error}", True)
     except (OSError, subprocess.SubprocessError) as bind_error:
-        return _reply_fallback(
-            f"{SOL_BIND_FAILURE_REASON}: {bind_error}", is_sol_enabled
-        )
+        return _reply_fallback(f"{SOL_BIND_FAILURE_REASON}: {bind_error}", True)
     if completed_process.returncode != 0:
         return _reply_fallback(
             f"{SOL_BIND_FAILURE_REASON}: process exit {completed_process.returncode}",
-            is_sol_enabled,
+            True,
         )
     return parse_codex_jsonl_reply(
         completed_process.stdout,
         existing_session_id=session_id,
-        is_sol_enabled=is_sol_enabled,
+        is_sol_enabled=True,
     )
 
 
@@ -417,6 +473,12 @@ def build_argument_parser() -> argparse.ArgumentParser:
     mode_group.add_argument("--bind", action="store_true")
     mode_group.add_argument("--resume", metavar=SOL_SESSION_ID_METAVAR)
     argument_parser.add_argument("--cwd", required=True, type=Path)
+    argument_parser.add_argument(
+        SOL_ENABLE_FLAG,
+        dest="is_sol_requested",
+        action="store_true",
+        help="Open the Sol rung for this invocation without an environment flag.",
+    )
     return argument_parser
 
 
@@ -430,12 +492,15 @@ def main(all_cli_arguments: Sequence[str]) -> int:
         Zero for a successful Sol response, or one for an explicit fallback.
     """
     parsed_arguments = build_argument_parser().parse_args(list(all_cli_arguments))
+    setting_by_name: Mapping[str, str] = os.environ
+    if parsed_arguments.is_sol_requested:
+        setting_by_name = {**os.environ, SOL_ENV_VAR: "1"}
     advisor_reply = run_codex_sol_advisor(
         prompt=sys.stdin.read(),
         working_directory=parsed_arguments.cwd,
         preflight=None,
         probe_path=None,
-        setting_by_name=os.environ,
+        setting_by_name=setting_by_name,
         session_id=parsed_arguments.resume if not parsed_arguments.bind else None,
         process_runner=subprocess.run,
     )

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 CODEX_EXECUTABLE: str = "codex"
+ADVISOR_CODEX_EXECUTABLE_ENV_VAR: str = "ADVISOR_CODEX_EXECUTABLE"
 CODEX_READ_ONLY_SANDBOX: str = "read-only"
 CODEX_JSON_FLAG: str = "--json"
 CODEX_MODEL_FLAG: str = "--model"
@@ -26,3 +27,7 @@ SOL_CODEX_TIMEOUT_REASON: str = "Codex Sol xhigh request timed out"
 SOL_MALFORMED_JSONL_REASON: str = "Codex Sol xhigh returned malformed JSONL"
 SOL_MISSING_SESSION_REASON: str = "Codex Sol xhigh returned no session id"
 SOL_INVALID_SIGNAL_REASON: str = "Codex Sol xhigh returned an invalid guidance signal"
+SOL_EXECUTABLE_NOT_FOUND_REASON: str = "Codex Sol xhigh could not find the codex executable on PATH"
+SOL_FALLBACK_KIND_DECLINED: str = "declined"
+SOL_FALLBACK_KIND_BROKEN: str = "broken"
+SOL_ENABLE_FLAG: str = "--enable-sol"

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

@@ -37,6 +37,17 @@ USAGE_PROBE_PATH = (
     / "scripts"
     / "codex_usage_probe.py"
 )
+WINDOWS_SHIM_PATH = r"C:\Users\me\AppData\Roaming\npm\codex.cmd"
+ENABLED_SETTING_BY_NAME = {sol_advisor.SOL_ENV_VAR: "1"}
+
+
+@pytest.fixture(autouse=True)
+def _codex_on_search_path(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        sol_advisor.shutil,
+        "which",
+        lambda name: "codex" if name == sol_advisor.CODEX_EXECUTABLE else None,
+    )
 
 
 def _probe_process(
@@ -130,6 +141,7 @@ def test_main_serializes_stable_result_field(monkeypatch: pytest.MonkeyPatch, ca
             sol_enabled=True,
         selected_tier=sol_advisor.ADVISOR_MODEL_TIER,
         outcome=sol_advisor.CODEX_BIND_SUCCESS_TOKEN,
+        fallback_kind=None,
         ),
     )
     monkeypatch.setattr(sys, "stdin", io.StringIO("first consult"))
@@ -155,18 +167,165 @@ def test_bind_and_resume_arguments_match_installed_codex_interface() -> None:
         "read-only",
         "--json",
     ]
-    assert sol_advisor.build_codex_arguments() == [
+    assert sol_advisor.build_codex_arguments("codex") == [
         *expected_common_arguments,
         "-",
     ]
-    assert sol_advisor.build_codex_arguments("thread-1") == [
-        *expected_common_arguments,
+    assert sol_advisor.build_codex_arguments(
+        WINDOWS_SHIM_PATH, session_id="thread-1"
+    ) == [
+        WINDOWS_SHIM_PATH,
+        *expected_common_arguments[1:],
         "resume",
         "thread-1",
         "-",
     ]
 
 
+def test_resolve_codex_executable_prefers_the_env_var_override(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sol_advisor.shutil, "which", lambda name: None)
+
+    resolved_executable = sol_advisor.resolve_codex_executable(
+        {sol_advisor.ADVISOR_CODEX_EXECUTABLE_ENV_VAR: WINDOWS_SHIM_PATH}
+    )
+
+    assert resolved_executable == WINDOWS_SHIM_PATH
+
+
+def test_resolve_codex_executable_falls_back_to_which_search(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        sol_advisor.shutil,
+        "which",
+        lambda name: (
+            WINDOWS_SHIM_PATH if name == sol_advisor.CODEX_EXECUTABLE else None
+        ),
+    )
+
+    resolved_executable = sol_advisor.resolve_codex_executable({})
+
+    assert resolved_executable == WINDOWS_SHIM_PATH
+
+
+def test_resolve_codex_executable_returns_none_when_unresolved(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sol_advisor.shutil, "which", lambda name: None)
+
+    resolved_executable = sol_advisor.resolve_codex_executable({})
+
+    assert resolved_executable is None
+
+
+def test_bind_falls_back_with_a_clear_reason_when_executable_is_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sol_advisor.shutil, "which", lambda name: None)
+    calls: list[list[str]] = []
+
+    def process_runner(
+        arguments: list[str], **kwargs: object
+    ) -> subprocess.CompletedProcess[str]:
+        calls.append(arguments)
+        return _probe_process({"percent_left": 90})
+
+    reply = sol_advisor.run_codex_sol_advisor(
+        prompt="first consult",
+        working_directory=Path("."),
+        preflight=None,
+        probe_path=USAGE_PROBE_PATH,
+        session_id=None,
+        process_runner=process_runner,
+        setting_by_name={sol_advisor.SOL_ENV_VAR: "1"},
+    )
+
+    assert not reply.successful
+    assert reply.is_fallback
+    assert reply.reason is not None
+    assert "codex" in reply.reason
+    assert reply.fallback_kind == sol_advisor.SOL_FALLBACK_KIND_BROKEN
+    assert calls == []
+
+
+def test_policy_fallbacks_are_marked_declined() -> None:
+    def gate_closed_runner(
+        arguments: list[str], **kwargs: object
+    ) -> subprocess.CompletedProcess[str]:
+        return _probe_process({"percent_left": 5})
+
+    disabled_reply = sol_advisor.run_codex_sol_advisor(
+        prompt="first consult",
+        working_directory=Path("."),
+        preflight=None,
+        probe_path=USAGE_PROBE_PATH,
+        session_id=None,
+        process_runner=gate_closed_runner,
+        setting_by_name={},
+    )
+    gate_closed_reply = sol_advisor.run_codex_sol_advisor(
+        prompt="first consult",
+        working_directory=Path("."),
+        preflight=None,
+        probe_path=USAGE_PROBE_PATH,
+        session_id=None,
+        process_runner=gate_closed_runner,
+        setting_by_name=ENABLED_SETTING_BY_NAME,
+    )
+
+    assert disabled_reply.fallback_kind == sol_advisor.SOL_FALLBACK_KIND_DECLINED
+    assert gate_closed_reply.fallback_kind == sol_advisor.SOL_FALLBACK_KIND_DECLINED
+
+
+def test_probe_failure_fallback_is_marked_broken() -> None:
+    def failing_probe_runner(
+        arguments: list[str], **kwargs: object
+    ) -> subprocess.CompletedProcess[str]:
+        return _probe_process({}, returncode=3)
+
+    reply = sol_advisor.run_codex_sol_advisor(
+        prompt="first consult",
+        working_directory=Path("."),
+        preflight=None,
+        probe_path=USAGE_PROBE_PATH,
+        session_id=None,
+        process_runner=failing_probe_runner,
+        setting_by_name=ENABLED_SETTING_BY_NAME,
+    )
+
+    assert reply.is_fallback
+    assert reply.fallback_kind == sol_advisor.SOL_FALLBACK_KIND_BROKEN
+
+
+def test_enable_sol_flag_opens_the_rung_without_an_environment_flag(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    captured_settings: dict[str, str] = {}
+
+    def fake_advisor(**kwargs: object) -> object:
+        captured_settings.update(dict(kwargs["setting_by_name"]))  # type: ignore[arg-type]
+        return sol_advisor._reply_fallback(
+            "probe declined",
+            True,
+            fallback_kind=sol_advisor.SOL_FALLBACK_KIND_DECLINED,
+        )
+
+    monkeypatch.setattr(sol_advisor, "run_codex_sol_advisor", fake_advisor)
+    monkeypatch.delenv(sol_advisor.SOL_ENV_VAR, raising=False)
+    monkeypatch.setattr(sys, "stdin", io.StringIO("first consult"))
+
+    exit_code = sol_advisor.main(
+        ["--bind", "--cwd", ".", sol_advisor.SOL_ENABLE_FLAG]
+    )
+    payload = json.loads(capsys.readouterr().out)
+
+    assert exit_code == 1
+    assert captured_settings[sol_advisor.SOL_ENV_VAR] == "1"
+    assert payload["fallback_kind"] == sol_advisor.SOL_FALLBACK_KIND_DECLINED
+
+
 def test_successful_probe_requires_finite_meter_above_configured_gate() -> None:
     def probe_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
         return _probe_process({"percent_left": 90})
@@ -304,12 +463,12 @@ def test_bind_runs_probe_then_codex_with_read_only_xhigh_settings() -> None:
         probe_path=USAGE_PROBE_PATH,
         session_id=None,
         process_runner=process_runner,
-        setting_by_name={"ADVISOR_SOL_XHIGH": "1"},
+        setting_by_name=ENABLED_SETTING_BY_NAME,
     )
 
     assert reply.successful
     assert len(calls) == 2
-    assert calls[1][0] == sol_advisor.build_codex_arguments()
+    assert calls[1][0] == sol_advisor.build_codex_arguments("codex")
     assert calls[1][1]["cwd"] == "."
     assert calls[1][1]["shell"] is False
     assert calls[1][1]["timeout"]
@@ -331,7 +490,7 @@ def test_team_advisor_path_preserves_sol_routing_fields() -> None:
         probe_path=USAGE_PROBE_PATH,
         session_id=None,
         process_runner=_two_step_process_runner(calls, guidance="PLAN\ninspect"),
-        setting_by_name={"ADVISOR_SOL_XHIGH": "1"},
+        setting_by_name=ENABLED_SETTING_BY_NAME,
     )
 
     assert reply.successful
@@ -358,7 +517,7 @@ def test_team_advisor_path_uses_fable_result_when_sol_gate_is_closed() -> None:
         probe_path=USAGE_PROBE_PATH,
         session_id=None,
         process_runner=process_runner,
-        setting_by_name={"ADVISOR_SOL_XHIGH": "1"},
+        setting_by_name=ENABLED_SETTING_BY_NAME,
     )
 
     assert not reply.successful
@@ -369,7 +528,10 @@ def test_team_advisor_path_uses_fable_result_when_sol_gate_is_closed() -> None:
     assert len(calls) == 1
 
 
-def test_disabled_flag_uses_default_optional_routing_inputs() -> None:
+def test_disabled_flag_uses_default_optional_routing_inputs(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv(sol_advisor.SOL_ENV_VAR, raising=False)
     reply = sol_advisor.run_codex_sol_advisor(
         prompt="first consult",
         working_directory=Path("."),
@@ -398,13 +560,13 @@ def test_resume_runs_the_usage_gate_before_codex() -> None:
         session_id="thread-1",
         probe_path=USAGE_PROBE_PATH,
         process_runner=_two_step_process_runner(calls, guidance="ENDORSE\nready"),
-        setting_by_name={"ADVISOR_SOL_XHIGH": "1"},
+        setting_by_name=ENABLED_SETTING_BY_NAME,
     )
 
     assert reply.successful
     assert calls == [
         [sys.executable, str(USAGE_PROBE_PATH)],
-        sol_advisor.build_codex_arguments("thread-1"),
+        sol_advisor.build_codex_arguments("codex", session_id="thread-1"),
     ]
 
 
@@ -465,7 +627,7 @@ def test_codex_failure_modes_always_return_fallback(
         probe_path=USAGE_PROBE_PATH,
         session_id=None,
         process_runner=process_runner,
-        setting_by_name={"ADVISOR_SOL_XHIGH": "1"},
+        setting_by_name=ENABLED_SETTING_BY_NAME,
     )
 
     assert not reply.successful

package/commands/CLAUDE.md

@@ -15,6 +15,7 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
 | `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
 | `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
+| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
 | `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
 
 ## Format

package/commands/sr-loop.md

@@ -0,0 +1,48 @@
+---
+description: Converging cleanup loop - repeat /simplify until clean, then repeat /code-review --fix until clean
+argument-hint: [PR URL, branch, or blank for the current diff]
+---
+
+Run the converging cleanup loop on the target: `$ARGUMENTS` (blank means the
+current branch's diff). Each phase invokes an existing skill with the Skill
+tool and repeats it until a pass returns zero new findings.
+
+## Phase A — loop /simplify
+
+1. Invoke the `simplify` skill on the target (the same review the user gets
+   from `/simplify <target>`). Let it run its 4-lens fan-out and apply its
+   fixes.
+2. After each pass: run the scoped test suite (test files beside the touched
+   code, not the full repo suite), commit once (`git commit -F <file>`, body
+   written with the Write tool, Co-Authored-By line, 10-minute timeout — the
+   pre-commit gate runs its own tests), and push to the PR head branch. The PR
+   stays draft.
+3. Repeat the invocation. **Skips are sticky:** carry every adjudicated skip
+   forward into the next pass as "already adjudicated — do not re-report: ..."
+   context, or the loop never converges.
+4. Phase A converges when a full pass returns zero new findings. When the
+   previous pass changed only a line or two, a single combined-lens
+   confirmation agent may serve as the final pass.
+
+## Phase B — loop /code-review low --fix
+
+1. Invoke the `code-review` skill with arguments `low --fix` on the same
+   target. Let it report findings and apply its fixes.
+2. After any pass that changed files: test, commit, push as in Phase A.
+3. Repeat until a pass reports zero findings. Phase B usually converges in one
+   pass when Phase A ran first.
+
+## Finish
+
+Report: passes run per phase, commits pushed with hashes, fixes applied, and
+the standing skip list with reasons.
+
+## Constraints (observed under headless runs)
+
+- Run this loop in the main session. A wrapper subagent cannot see the
+  `code-review` skill, and a nested agent's own subagent reports route to the
+  main session instead of back to it.
+- Scope test runs to the touched files; a full-suite run can outlive one
+  foreground tool call.
+- A hung or newly slow test suite is a finding to investigate, not an
+  inconvenience.

package/package.json

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

package/skills/usage-pause/SKILL.md

@@ -44,7 +44,7 @@ On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset ti
 In short: the resolver picks a bearer token, probes the OAuth usage endpoint the interactive `/usage` panel uses, and returns the session and weekly buckets with utilization and reset times. Token sources depend on the host:
 
 - **Desktop host** (the `CLAUDE_CODE_ENTRYPOINT` variable is `claude-desktop`): the resolver does not read the CLI credential file, which belongs to a different authentication session than the one the desktop app counts usage against. It uses the session ingress token when one is set, and otherwise takes the manual-override path.
-- **Every other host**: the resolver reads the Claude Code CLI's stored OAuth access token first (honored only while unexpired), then the session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions) when the credential token is unavailable.
+- **Every other host**: the resolver reads the Claude Code CLI's stored OAuth access token first (honored only while unexpired), then the session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions) when the credential token is unavailable. The credential file lives under the directory `CLAUDE_CONFIG_DIR` names when that variable is set — a profile-isolated session's own account — else the home-directory default; the home file on a multi-profile machine can belong to a different account, whose meter is the wrong one to read.
 
 Fallbacks, in order: both token sources unavailable (expired/unreadable credential and no ingress file), a failed request, or a response with no readable session-window reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are unavailable.
 

package/skills/usage-pause/scripts/resolve_usage_window.py

@@ -9,8 +9,10 @@
 
 With no ``--override``, the script resolves a bearer token. On the desktop
 host it uses only the session ingress token. On every other host it reads the
-Claude Code OAuth access token from the CLI credential file, then the session
-ingress token file when that credential is unavailable. It asks the OAuth
+Claude Code OAuth access token from the CLI credential file — under the
+directory ``CLAUDE_CONFIG_DIR`` names when set, else the home-directory
+default — then the session ingress token file when that credential is
+unavailable. It asks the OAuth
 usage endpoint for the ``five_hour`` and ``seven_day`` windows. Exit code 2
 means the probe cannot resolve; the caller then asks the user for a manual
 reset time.
@@ -38,10 +40,12 @@ from usage_pause_constants.resolve_usage_window_constants import (
     BARE_MINUTES_PATTERN,
     CLOCK_HOUR_MAXIMUM,
     CLOCK_PATTERN,
+    CONFIG_DIR_ENV_VAR,
     CONTENT_TYPE_HEADER_NAME,
     CONTENT_TYPE_JSON,
     CREDENTIALS_ACCESS_TOKEN_KEY,
     CREDENTIALS_EXPIRES_AT_KEY,
+    CREDENTIALS_FILE_NAME,
     CREDENTIALS_OAUTH_SECTION_KEY,
     DESKTOP_ENTRYPOINT_VALUE,
     DURATION_PATTERN,
@@ -203,6 +207,27 @@ def plan_wakeup_stages(seconds_until_reset: int) -> list[int]:
     return stages
 
 
+def default_credentials_path() -> Path:
+    """Locate the CLI credential file for the account this session runs as.
+
+    ::
+
+        CLAUDE_CONFIG_DIR=C:/profiles/mel  ->  C:/profiles/mel/.credentials.json
+        (variable unset or empty)          ->  ~/.claude/.credentials.json
+
+    A profile-isolated session keeps its credential under the config-dir
+    directory. On such a machine the home file belongs to a different
+    account. Reading the home file reports that other account's meter.
+
+    Returns:
+        The credential file for the session's own account.
+    """
+    config_directory = os.environ.get(CONFIG_DIR_ENV_VAR)
+    if config_directory:
+        return Path(config_directory) / CREDENTIALS_FILE_NAME
+    return Path.home().joinpath(*ALL_CREDENTIALS_RELATIVE_PATH_PARTS)
+
+
 def read_oauth_access_token(credentials_path: Path, now: datetime) -> str | None:
     """Read the CLI's OAuth access token when it is still valid.
 
@@ -523,7 +548,10 @@ def _parse_arguments() -> argparse.Namespace:
     parser.add_argument(
         "--credentials-path",
         default=None,
-        help="Path to the CLI credential file; defaults to the home-directory location.",
+        help=(
+            "Path to the CLI credential file; defaults to the CLAUDE_CONFIG_DIR "
+            "location when that variable is set, else the home-directory location."
+        ),
     )
     return parser.parse_args()
 
@@ -558,7 +586,7 @@ def main() -> int:
     credentials_path = (
         Path(arguments.credentials_path)
         if arguments.credentials_path
-        else Path.home().joinpath(*ALL_CREDENTIALS_RELATIVE_PATH_PARTS)
+        else default_credentials_path()
     )
     access_token = resolve_access_token(credentials_path, now)
     if access_token is None:

package/skills/usage-pause/scripts/test_resolve_usage_window.py

@@ -19,6 +19,7 @@ if str(SCRIPTS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIRECTORY))
 
 from usage_pause_constants.resolve_usage_window_constants import (  # noqa: E402
+    CONFIG_DIR_ENV_VAR,
     DESKTOP_ENTRYPOINT_VALUE,
     ENTRYPOINT_ENV_VAR,
     SESSION_INGRESS_TOKEN_FILE_ENV_VAR as INGRESS_TOKEN_FILE_ENV_VAR,
@@ -195,6 +196,31 @@ class TestReadOauthAccessToken:
         assert any("unreadable" in each_message for each_message in caplog.messages)
 
 
+class TestDefaultCredentialsPath:
+    def should_use_the_config_dir_credential_file_when_the_variable_is_set(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(CONFIG_DIR_ENV_VAR, str(tmp_path))
+        assert resolver.default_credentials_path() == tmp_path / ".credentials.json"
+
+    def should_fall_back_to_the_home_credential_file_when_the_variable_is_unset(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.delenv(CONFIG_DIR_ENV_VAR, raising=False)
+        expected = Path.home() / ".claude" / ".credentials.json"
+        assert resolver.default_credentials_path() == expected
+
+    def should_fall_back_to_the_home_credential_file_when_the_variable_is_empty(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(CONFIG_DIR_ENV_VAR, "")
+        expected = Path.home() / ".claude" / ".credentials.json"
+        assert resolver.default_credentials_path() == expected
+
+
 class TestReadSessionIngressToken:
     def should_return_stripped_token_from_the_named_file(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch

package/skills/usage-pause/scripts/usage_pause_constants/resolve_usage_window_constants.py

@@ -19,6 +19,8 @@ CONTENT_TYPE_JSON = "application/json"
 PROBE_TIMEOUT_SECONDS = 10
 
 ALL_CREDENTIALS_RELATIVE_PATH_PARTS = (".claude", ".credentials.json")
+CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+CREDENTIALS_FILE_NAME = ".credentials.json"
 CREDENTIALS_OAUTH_SECTION_KEY = "claudeAiOauth"
 CREDENTIALS_ACCESS_TOKEN_KEY = "accessToken"
 CREDENTIALS_EXPIRES_AT_KEY = "expiresAt"
@@ -67,4 +69,4 @@ SOURCE_OVERRIDE = "override"
 EXIT_CODE_RESOLVED = 0
 EXIT_CODE_PROBE_UNAVAILABLE = 2
 
-LOGGING_FORMAT = "%(levelname)s %(name)s: %(message)s"
+LOGGING_FORMAT = "%(levelname)s %(name)s: %(message)s"