claude-dev-env 2.2.0 → 2.3.0

package/skills/pr-converge/reference/per-tick.md

@@ -71,7 +71,7 @@ Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
 The **PR worktree** is the local working tree of the PR's repo on its head
 branch. Every local operation this tick runs there: the CODE_REVIEW static sweep
-and `/code-review high --fix`, every `clean-coder` fix spawn, and every commit and
+and `/code-review xhigh --fix`, every `clean-coder` fix spawn, and every commit and
 push. `/code-review` and `git` both act on the repo of the current working
 directory, so the working directory must be the PR worktree before any local
 work begins. Re-resolve it every tick — a rebase or a fresh HEAD can move the
@@ -180,7 +180,7 @@ CODE_REVIEW.
 ### `phase == CODE_REVIEW`
 
 The entry phase of every convergence tick, re-entered after any fix push. It runs
-a deterministic static sweep, then the built-in `/code-review high --fix` on the
+a deterministic static sweep, then the built-in `/code-review xhigh --fix` on the
 full `origin/main...HEAD` diff at effort high on model opus. `/code-review`
 produces no GitHub review artifact, so there are no code-review threads to
 resolve.
@@ -196,7 +196,7 @@ a. **Static sweep — runs first, before `/code-review`.** Run the deterministic
    `phase = CODE_REVIEW`, and re-run the sweep. When the sweep is clean, run
    the host-aware review below.
 
-b. Run the built-in `/code-review high --fix` on the FULL `origin/main...HEAD`
+b. Run the built-in `/code-review xhigh --fix` with OPUS on the FULL `origin/main...HEAD`
    diff — every file the PR touches — via the
    [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
    The review always runs at effort high on model opus. It reviews the diff and
@@ -231,14 +231,14 @@ b. Run the built-in `/code-review high --fix` on the FULL `origin/main...HEAD`
    Match the first mode whose predicate holds:
 
    - **`mode == "in_session"`** (Claude host and session model is opus): run
-     `/code-review high --fix` in this session with no path arguments so it
+     `/code-review xhigh --fix` with OPUS in this session with no path arguments so it
      audits the whole branch diff against `origin/main`. After it returns, a
      non-empty `git status --porcelain` means fixes applied (`dirty_tree`
      equivalent). Treat a failed in-session slash command the same as a failed
      review: do not set `code_review_clean_at`.
    - **`mode == "chain"`** (any other host, or a Claude session on any model
      other than opus): the helper already ran the headless review
-     (`claude -p "/code-review high --fix" --model opus` through the chain
+     (`claude -p "/code-review xhigh --fix" --model opus` through the chain
      runner) with cwd set to the PR worktree. Read `returncode`,
      `served_command`, and `dirty_tree` from the JSON. A successful serve is
      `returncode == 0` with a non-null `served_command`. `dirty_tree` true

package/skills/pr-converge/reference/progress-checklist.md

@@ -91,7 +91,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **Static sweep fails** → apply shared fix protocol → push → reset markers
             → stay CODE_REVIEW → Step 5
       - [ ] **`mode == in_session`** (Claude host, session model opus) → run
-            `/code-review high --fix` in-session (no path args)
+            `/code-review xhigh --fix` in-session (no path args)
       - [ ] **`mode == chain`** (any other host or non-opus session) → helper
             already ran the headless review; read `returncode`,
             `served_command`, and `dirty_tree` from JSON

package/skills/pr-converge/test_step5_host_branch.py

@@ -32,7 +32,7 @@ NEVER_PUSHES_PHRASE = "never pushes"
 EMPTY_STDIN_PHRASE = "empty"
 CWD_FLAG = "--cwd"
 OPUS_MODEL = "opus"
-HIGH_EFFORT_SLASH = "/code-review high --fix"
+HIGH_EFFORT_SLASH = "/code-review xhigh --fix"
 
 
 def _read_markdown(markdown_path: Path) -> str:

package/skills/team-advisor/SKILL.md

@@ -30,8 +30,9 @@ the only consumer (skip the "who you are and your assignment" opener in each
 consult; a single-consumer session doesn't need it).
 
 **Third-party host:** bind a max-tier Claude advisor through the shared CLI Claude-chain
-in the protocol (Fable max, then Opus max; `claude_chain_runner.py` walks
-`~/.claude/claude-chain.json` for account usage failover). Consult via
+in the protocol (Fable max, then Opus max; `claude_chain_runner.py` ranks
+`~/.claude/claude-chain.json` accounts by weekly remaining via `claude_chain_usage`
+and fails over on usage limits). Consult via
 `--resume <session_id>` on that bind. This session is the sole consumer of that
 CLI advisor; skip the multi-consumer opener. When the chain cannot bind or
 reply, fail closed and report to the user — do **not** answer ENDORSE /

package/skills/usage-pause/SKILL.md

@@ -41,10 +41,10 @@ On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset ti
 
 `scripts/resolve_usage_window.py` is the source of truth for live probe behavior. Endpoint URL, header names/values, credential path and token keys, response bucket keys, stage sizing, and the weekly warn threshold all live in `scripts/usage_pause_constants/resolve_usage_window_constants.py` — read those modules for the current values; do not restate them here.
 
-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, in order:
+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:
 
-1. The Claude Code CLI's stored OAuth access token (honored only while unexpired).
-2. The session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions).
+- **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.
 
 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.
 
@@ -106,8 +106,9 @@ Fill each `<slot>` at schedule time: `<remaining_stage_durations>` is the tail o
 | `SKILL.md` | This flow: resolve, weekly guard, stage chain, templates |
 | `scripts/resolve_usage_window.py` | The window resolver and stage planner CLI |
 | `scripts/test_resolve_usage_window.py` | Behavioral tests for parsing, staging, token reading, extraction, CLI |
-| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, stage sizing, thresholds, result keys |
+| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, host detection, stage sizing, thresholds, result keys |
 
 ## Gotchas
 
 - The stored access token lives about 8 hours and the CLI rewrites it on its own schedule, so a mid-afternoon probe can find it expired even while the CLI itself still works. That is the designed exit-2 path: give a manual time.
+- On the desktop host the resolver never reads the CLI credential file, because that credential is a different authentication session than the one the desktop app counts usage against. With no session ingress token set, the desktop host takes the manual path: read the reset time from the interactive `/usage` panel and pass it, for example `/usage-pause 10:20pm`.

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

@@ -7,11 +7,13 @@
     {"source": "override", "reset_at": "2026-07-08T10:14:00-07:00",
      "seconds_until_reset": 4440, "stages_seconds": [3480, 960, 120], ...}
 
-With no ``--override``, the script resolves a bearer token: the Claude Code
-OAuth access token from the CLI credential file, or 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.
+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
+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.
 """
 
 from __future__ import annotations
@@ -41,7 +43,9 @@ from usage_pause_constants.resolve_usage_window_constants import (
     CREDENTIALS_ACCESS_TOKEN_KEY,
     CREDENTIALS_EXPIRES_AT_KEY,
     CREDENTIALS_OAUTH_SECTION_KEY,
+    DESKTOP_ENTRYPOINT_VALUE,
     DURATION_PATTERN,
+    ENTRYPOINT_ENV_VAR,
     EPOCH_MILLISECONDS_THRESHOLD,
     EXIT_CODE_PROBE_UNAVAILABLE,
     EXIT_CODE_RESOLVED,
@@ -267,14 +271,36 @@ def read_session_ingress_token() -> str | None:
     return token_text
 
 
+def running_on_desktop_host() -> bool:
+    """Tell whether this process runs under the Claude desktop app.
+
+    ::
+
+        entrypoint is the desktop marker  ->  True
+        entrypoint is the CLI or unset    ->  False
+
+    The desktop app meters its session under a different auth session than
+    the CLI credential file, so a true answer tells the resolver to leave
+    that credential file alone.
+
+    Returns:
+        True when the entrypoint environment variable names the desktop app.
+    """
+    return os.environ.get(ENTRYPOINT_ENV_VAR) == DESKTOP_ENTRYPOINT_VALUE
+
+
 def resolve_access_token(credentials_path: Path, now: datetime) -> str | None:
     """Choose the usage-endpoint bearer token from its available sources.
 
     ::
 
-        credential file token valid   ->  the credential token
-        credential token unavailable  ->  the session ingress token
-        neither source available      ->  None
+        CLI host, credential token valid        ->  the credential token
+        CLI host, credential token unavailable   ->  the session ingress token
+        desktop host                             ->  the session ingress token
+        no source available                      ->  None
+
+    On the desktop host the CLI credential file belongs to a different auth
+    session, so it is skipped and only the session ingress token is honored.
 
     Args:
         credentials_path: The CLI credential file holding the OAuth section.
@@ -283,6 +309,8 @@ def resolve_access_token(credentials_path: Path, now: datetime) -> str | None:
     Returns:
         The bearer token for the usage endpoint, or None when no source has one.
     """
+    if running_on_desktop_host():
+        return read_session_ingress_token()
     credential_token = read_oauth_access_token(credentials_path, now)
     return credential_token or read_session_ingress_token()
 
@@ -447,6 +475,37 @@ def _describe_ingress_token_source() -> str:
     return f"the session ingress token file ({SESSION_INGRESS_TOKEN_FILE_ENV_VAR} set but empty)"
 
 
+def _no_token_error_message(credentials_path: Path) -> str:
+    """Build the no-usable-token exit-2 error, host-aware for the desktop app.
+
+    ::
+
+        desktop host  ->  names the different-session skip and the /usage remedy
+        other host    ->  names the credential path and the ingress source tried
+
+    On the desktop host the CLI credential file is never read, so the message
+    points the user at the interactive /usage panel for a manual reset time.
+
+    Args:
+        credentials_path: The CLI credential file the non-desktop message names.
+
+    Returns:
+        The error text for the no-usable-token exit-2 path.
+    """
+    if running_on_desktop_host():
+        return (
+            "on the desktop host the CLI credential file belongs to a different "
+            f"auth session and is not read, and {_describe_ingress_token_source()} "
+            "has no token; read the reset time from the interactive /usage panel "
+            "and give it manually, for example /usage-pause 10:20pm or /usage-pause 74m"
+        )
+    return (
+        "no usable bearer token from the OAuth credential file at "
+        f"{credentials_path} or {_describe_ingress_token_source()}; give a "
+        "manual reset time, for example /usage-pause 10:20pm or /usage-pause 74m"
+    )
+
+
 def _parse_arguments() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Resolve the 5-hour usage window reset and plan the pause stage chain.",
@@ -503,11 +562,7 @@ def main() -> int:
     )
     access_token = resolve_access_token(credentials_path, now)
     if access_token is None:
-        return _emit_error(
-            "no usable bearer token from the OAuth credential file at "
-            f"{credentials_path} or {_describe_ingress_token_source()}; give a "
-            "manual reset time, for example /usage-pause 10:20pm or /usage-pause 74m"
-        )
+        return _emit_error(_no_token_error_message(credentials_path))
     try:
         usage_payload = _fetch_usage_payload(access_token)
     except (

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

@@ -18,7 +18,9 @@ SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
 if str(SCRIPTS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIRECTORY))
 
-from usage_pause_constants.resolve_usage_window_constants import (
+from usage_pause_constants.resolve_usage_window_constants import (  # noqa: E402
+    DESKTOP_ENTRYPOINT_VALUE,
+    ENTRYPOINT_ENV_VAR,
     SESSION_INGRESS_TOKEN_FILE_ENV_VAR as INGRESS_TOKEN_FILE_ENV_VAR,
 )
 
@@ -188,8 +190,7 @@ class TestReadOauthAccessToken:
         credentials_path.write_text("{not valid json", encoding="utf-8")
         with caplog.at_level(logging.WARNING):
             assert (
-                resolver.read_oauth_access_token(credentials_path, local_now())
-                is None
+                resolver.read_oauth_access_token(credentials_path, local_now()) is None
             )
         assert any("unreadable" in each_message for each_message in caplog.messages)
 
@@ -240,7 +241,43 @@ class TestReadSessionIngressToken:
         assert INGRESS_TOKEN_FILE_ENV_VAR == "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
 
 
+class TestRunningOnDesktopHost:
+    def should_be_true_when_entrypoint_names_the_desktop_app(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(ENTRYPOINT_ENV_VAR, DESKTOP_ENTRYPOINT_VALUE)
+        assert resolver.running_on_desktop_host() is True
+
+    def should_be_false_when_entrypoint_names_a_non_desktop_host(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(ENTRYPOINT_ENV_VAR, "cli")
+        assert resolver.running_on_desktop_host() is False
+
+    def should_be_false_when_entrypoint_is_unset(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.delenv(ENTRYPOINT_ENV_VAR, raising=False)
+        assert resolver.running_on_desktop_host() is False
+
+    def should_pin_the_desktop_entrypoint_contract_to_the_literal_marker(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv("CLAUDE_CODE_ENTRYPOINT", "claude-desktop")
+        assert resolver.running_on_desktop_host() is True
+        assert ENTRYPOINT_ENV_VAR == "CLAUDE_CODE_ENTRYPOINT"
+        assert DESKTOP_ENTRYPOINT_VALUE == "claude-desktop"
+
+
 class TestResolveAccessToken:
+    @pytest.fixture(autouse=True)
+    def force_non_desktop_host(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv(ENTRYPOINT_ENV_VAR, raising=False)
+
     def should_use_ingress_token_when_credential_file_missing(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
@@ -295,6 +332,57 @@ class TestResolveAccessToken:
         assert resolver.resolve_access_token(missing_credentials, local_now()) is None
 
 
+class TestResolveAccessTokenHostAware:
+    def should_ignore_a_valid_cli_credential_token_on_the_desktop_host(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        now = local_now()
+        credentials_path = tmp_path / ".credentials.json"
+        future_milliseconds = int((now + timedelta(hours=1)).timestamp() * 1000)
+        write_credentials(
+            credentials_path, future_milliseconds, access_token="cli-credential-token"
+        )
+        monkeypatch.setenv(ENTRYPOINT_ENV_VAR, DESKTOP_ENTRYPOINT_VALUE)
+        monkeypatch.delenv(INGRESS_TOKEN_FILE_ENV_VAR, raising=False)
+        chosen_token = resolver.resolve_access_token(credentials_path, now)
+        assert chosen_token != "cli-credential-token"
+        assert chosen_token is None
+
+    def should_use_the_ingress_token_over_the_cli_credential_on_the_desktop_host(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        now = local_now()
+        credentials_path = tmp_path / ".credentials.json"
+        future_milliseconds = int((now + timedelta(hours=1)).timestamp() * 1000)
+        write_credentials(
+            credentials_path, future_milliseconds, access_token="cli-credential-token"
+        )
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("ingress-token-value", encoding="utf-8")
+        monkeypatch.setenv(ENTRYPOINT_ENV_VAR, DESKTOP_ENTRYPOINT_VALUE)
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        chosen_token = resolver.resolve_access_token(credentials_path, now)
+        assert chosen_token == "ingress-token-value"
+        assert chosen_token != "cli-credential-token"
+
+    def should_return_the_cli_credential_token_on_a_non_desktop_host(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        now = local_now()
+        credentials_path = tmp_path / ".credentials.json"
+        future_milliseconds = int((now + timedelta(hours=1)).timestamp() * 1000)
+        write_credentials(
+            credentials_path, future_milliseconds, access_token="cli-credential-token"
+        )
+        monkeypatch.setenv(ENTRYPOINT_ENV_VAR, "cli")
+        monkeypatch.delenv(INGRESS_TOKEN_FILE_ENV_VAR, raising=False)
+        chosen_token = resolver.resolve_access_token(credentials_path, now)
+        assert chosen_token == "cli-credential-token"
+
+
 class TestExtractUsageWindows:
     def should_extract_session_and_weekly_buckets(self) -> None:
         resolver = load_resolver_module()
@@ -361,13 +449,20 @@ class TestBuildPausePlan:
 
 class TestCommandLine:
     def run_resolver(
-        self, *arguments: str, ingress_token_file: str | None = None
+        self,
+        *arguments: str,
+        ingress_token_file: str | None = None,
+        entrypoint: str | None = None,
     ) -> subprocess.CompletedProcess[str]:
         child_environment = dict(os.environ)
         if ingress_token_file is None:
             child_environment.pop(INGRESS_TOKEN_FILE_ENV_VAR, None)
         else:
             child_environment[INGRESS_TOKEN_FILE_ENV_VAR] = ingress_token_file
+        if entrypoint is None:
+            child_environment.pop(ENTRYPOINT_ENV_VAR, None)
+        else:
+            child_environment[ENTRYPOINT_ENV_VAR] = entrypoint
         return subprocess.run(
             [sys.executable, str(RESOLVER_PATH), *arguments],
             capture_output=True,
@@ -403,9 +498,7 @@ class TestCommandLine:
         assert str(missing_path) in resolved_payload["error"]
         assert f"{INGRESS_TOKEN_FILE_ENV_VAR} unset" in resolved_payload["error"]
 
-    def should_name_the_ingress_token_path_in_the_error(
-        self, tmp_path: Path
-    ) -> None:
+    def should_name_the_ingress_token_path_in_the_error(self, tmp_path: Path) -> None:
         missing_credentials = tmp_path / "absent.json"
         stale_ingress = tmp_path / "stale-ingress-token"
         completed = self.run_resolver(
@@ -429,10 +522,29 @@ class TestCommandLine:
         assert completed.returncode == 2
         resolved_payload = json.loads(completed.stdout)
         assert (
-            f"{INGRESS_TOKEN_FILE_ENV_VAR} set but empty"
-            in resolved_payload["error"]
+            f"{INGRESS_TOKEN_FILE_ENV_VAR} set but empty" in resolved_payload["error"]
         )
 
+    def should_exit_two_with_a_host_aware_error_on_the_desktop_host(
+        self, tmp_path: Path
+    ) -> None:
+        credentials_path = tmp_path / ".credentials.json"
+        future_milliseconds = int((local_now() + timedelta(hours=1)).timestamp() * 1000)
+        write_credentials(
+            credentials_path, future_milliseconds, access_token="cli-credential-token"
+        )
+        completed = self.run_resolver(
+            "--credentials-path",
+            str(credentials_path),
+            entrypoint="claude-desktop",
+        )
+        assert completed.returncode == 2
+        assert "cli-credential-token" not in completed.stdout
+        error_text = json.loads(completed.stdout)["error"]
+        assert "different auth session" in error_text
+        assert "/usage" in error_text
+        assert "/usage-pause" in error_text
+
     def should_reject_invalid_override_with_error_payload(self) -> None:
         completed = self.run_resolver("--override", "soon")
         assert completed.returncode == 2

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

@@ -1,9 +1,10 @@
 """Constants for the usage-window resolver.
 
 Groups: the OAuth usage-endpoint probe, the CLI credential file keys, the
-session ingress token file environment variable, the usage-response field
-keys, the override parse patterns, the wakeup stage sizing, the weekly warn
-threshold, the result JSON keys, the source labels, and the exit codes.
+session ingress token file environment variable, the host entrypoint
+detection, the usage-response field keys, the override parse patterns, the
+wakeup stage sizing, the weekly warn threshold, the result JSON keys, the
+source labels, and the exit codes.
 """
 
 from __future__ import annotations
@@ -24,6 +25,9 @@ CREDENTIALS_EXPIRES_AT_KEY = "expiresAt"
 SESSION_INGRESS_TOKEN_FILE_ENV_VAR = "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
 MILLISECONDS_PER_SECOND = 1000
 
+ENTRYPOINT_ENV_VAR = "CLAUDE_CODE_ENTRYPOINT"
+DESKTOP_ENTRYPOINT_VALUE = "claude-desktop"
+
 FIVE_HOUR_BUCKET_KEY = "five_hour"
 SEVEN_DAY_BUCKET_KEY = "seven_day"
 UTILIZATION_KEY = "utilization"