claude-dev-env 1.92.0 → 1.93.0

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

@@ -7,8 +7,9 @@
     {"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 reads the Claude Code OAuth access token
-from the CLI credential file and asks the OAuth usage endpoint for the
+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.
 """
@@ -18,6 +19,7 @@ from __future__ import annotations
 import argparse
 import json
 import logging
+import os
 import re
 import sys
 import urllib.error
@@ -67,6 +69,7 @@ from usage_pause_constants.resolve_usage_window_constants import (
     RESULT_KEY_WEEKLY_NEAR_CAP,
     RESULT_KEY_WEEKLY_RESETS_AT,
     RESULT_KEY_WEEKLY_UTILIZATION,
+    SESSION_INGRESS_TOKEN_FILE_ENV_VAR,
     SEVEN_DAY_BUCKET_KEY,
     SOURCE_OVERRIDE,
     SOURCE_PROBE,
@@ -212,6 +215,8 @@ def read_oauth_access_token(credentials_path: Path, now: datetime) -> str | None
     """
     try:
         credentials_payload = json.loads(credentials_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
     except (OSError, json.JSONDecodeError):
         logger.warning("credential file unreadable at %s", credentials_path)
         return None
@@ -234,6 +239,54 @@ def read_oauth_access_token(credentials_path: Path, now: datetime) -> str | None
     return access_token
 
 
+def read_session_ingress_token() -> str | None:
+    """Read the session ingress bearer token from its named file.
+
+    ::
+
+        (env var names /run/token)  ->  "<token text>"
+        (env var unset)             ->  None
+
+    Returns None when the environment variable is unset, and None with a
+    warning naming the path when the named file is unreadable or empty.
+
+    Returns:
+        The bearer token for the usage endpoint, or None when unavailable.
+    """
+    token_file_path = os.environ.get(SESSION_INGRESS_TOKEN_FILE_ENV_VAR)
+    if not token_file_path:
+        return None
+    try:
+        token_text = Path(token_file_path).read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        logger.warning("session ingress token file unreadable at %s", token_file_path)
+        return None
+    if not token_text:
+        logger.warning("session ingress token file empty at %s", token_file_path)
+        return None
+    return token_text
+
+
+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
+
+    Args:
+        credentials_path: The CLI credential file holding the OAuth section.
+        now: The current time the stored credential expiry is compared against.
+
+    Returns:
+        The bearer token for the usage endpoint, or None when no source has one.
+    """
+    credential_token = read_oauth_access_token(credentials_path, now)
+    return credential_token or read_session_ingress_token()
+
+
 def _parse_resets_at(raw_resets_at: object) -> datetime | None:
     if isinstance(raw_resets_at, bool):
         return None
@@ -370,6 +423,30 @@ def _emit_error(message: str) -> int:
     return EXIT_CODE_PROBE_UNAVAILABLE
 
 
+def _describe_ingress_token_source() -> str:
+    """Name the session ingress token source for the no-token error.
+
+    ::
+
+        (env var holds /run/token)  ->  "the session ingress token file at /run/token"
+        (env var unset)             ->  "the session ingress token file (... unset)"
+        (env var set but empty)     ->  "the session ingress token file (... set but empty)"
+
+    The operator reads which file the ingress lookup tried, learns the
+    environment variable was never set, or learns it was set to an empty value.
+
+    Returns:
+        A clause naming the ingress token file path, the unset variable, or the
+        set-but-empty variable.
+    """
+    ingress_token_file_path = os.environ.get(SESSION_INGRESS_TOKEN_FILE_ENV_VAR)
+    if ingress_token_file_path:
+        return f"the session ingress token file at {ingress_token_file_path}"
+    if ingress_token_file_path is None:
+        return f"the session ingress token file ({SESSION_INGRESS_TOKEN_FILE_ENV_VAR} unset)"
+    return f"the session ingress token file ({SESSION_INGRESS_TOKEN_FILE_ENV_VAR} set but empty)"
+
+
 def _parse_arguments() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Resolve the 5-hour usage window reset and plan the pause stage chain.",
@@ -424,11 +501,12 @@ def main() -> int:
         if arguments.credentials_path
         else Path.home().joinpath(*ALL_CREDENTIALS_RELATIVE_PATH_PARTS)
     )
-    access_token = read_oauth_access_token(credentials_path, now)
+    access_token = resolve_access_token(credentials_path, now)
     if access_token is None:
         return _emit_error(
-            "OAuth access token unavailable or expired; give a manual reset time, "
-            "for example /usage-pause 10:20pm or /usage-pause 74m"
+            "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"
         )
     try:
         usage_payload = _fetch_usage_payload(access_token)

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

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import importlib.util
 import json
+import logging
+import os
 import subprocess
 import sys
 from datetime import datetime, timedelta
@@ -13,12 +15,17 @@ from types import ModuleType
 import pytest
 
 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 (
+    SESSION_INGRESS_TOKEN_FILE_ENV_VAR as INGRESS_TOKEN_FILE_ENV_VAR,
+)
+
 RESOLVER_PATH = SCRIPTS_DIRECTORY / "resolve_usage_window.py"
 
 
 def load_resolver_module() -> ModuleType:
-    if str(SCRIPTS_DIRECTORY) not in sys.path:
-        sys.path.insert(0, str(SCRIPTS_DIRECTORY))
     spec = importlib.util.spec_from_file_location("resolve_usage_window", RESOLVER_PATH)
     assert spec is not None
     assert spec.loader is not None
@@ -32,6 +39,19 @@ def local_now() -> datetime:
     return datetime(2026, 7, 8, 9, 0, 0).astimezone()
 
 
+def write_credentials(
+    target: Path, expires_at_milliseconds: int, access_token: str = "token-value"
+) -> None:
+    payload = {
+        "claudeAiOauth": {
+            "accessToken": access_token,
+            "refreshToken": "refresh-value",
+            "expiresAt": expires_at_milliseconds,
+        }
+    }
+    target.write_text(json.dumps(payload), encoding="utf-8")
+
+
 class TestParseManualOverride:
     def should_parse_clock_time_with_pm_meridiem_to_same_day(self) -> None:
         resolver = load_resolver_module()
@@ -135,22 +155,12 @@ class TestPlanWakeupStages:
 
 
 class TestReadOauthAccessToken:
-    def write_credentials(self, target: Path, expires_at_milliseconds: int) -> None:
-        payload = {
-            "claudeAiOauth": {
-                "accessToken": "token-value",
-                "refreshToken": "refresh-value",
-                "expiresAt": expires_at_milliseconds,
-            }
-        }
-        target.write_text(json.dumps(payload), encoding="utf-8")
-
     def should_return_token_when_not_expired(self, tmp_path: Path) -> None:
         resolver = load_resolver_module()
         now = local_now()
         credentials_path = tmp_path / ".credentials.json"
         future_milliseconds = int((now + timedelta(hours=1)).timestamp() * 1000)
-        self.write_credentials(credentials_path, future_milliseconds)
+        write_credentials(credentials_path, future_milliseconds)
         assert resolver.read_oauth_access_token(credentials_path, now) == "token-value"
 
     def should_return_none_when_token_expired(self, tmp_path: Path) -> None:
@@ -158,13 +168,131 @@ class TestReadOauthAccessToken:
         now = local_now()
         credentials_path = tmp_path / ".credentials.json"
         past_milliseconds = int((now - timedelta(hours=1)).timestamp() * 1000)
-        self.write_credentials(credentials_path, past_milliseconds)
+        write_credentials(credentials_path, past_milliseconds)
         assert resolver.read_oauth_access_token(credentials_path, now) is None
 
-    def should_return_none_when_file_missing(self, tmp_path: Path) -> None:
+    def should_not_warn_when_credential_file_missing(
+        self, tmp_path: Path, caplog: pytest.LogCaptureFixture
+    ) -> None:
         resolver = load_resolver_module()
         missing_path = tmp_path / "absent.json"
-        assert resolver.read_oauth_access_token(missing_path, local_now()) is None
+        with caplog.at_level(logging.WARNING):
+            assert resolver.read_oauth_access_token(missing_path, local_now()) is None
+        assert caplog.records == []
+
+    def should_warn_when_credential_file_present_but_corrupt(
+        self, tmp_path: Path, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        resolver = load_resolver_module()
+        credentials_path = tmp_path / ".credentials.json"
+        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
+            )
+        assert any("unreadable" in each_message for each_message in caplog.messages)
+
+
+class TestReadSessionIngressToken:
+    def should_return_stripped_token_from_the_named_file(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("  ingress-token-value\n", encoding="utf-8")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        assert resolver.read_session_ingress_token() == "ingress-token-value"
+
+    def should_return_none_when_env_var_unset(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.delenv(INGRESS_TOKEN_FILE_ENV_VAR, raising=False)
+        assert resolver.read_session_ingress_token() is None
+
+    def should_return_none_when_named_file_missing(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(tmp_path / "absent-token"))
+        assert resolver.read_session_ingress_token() is None
+
+    def should_return_none_when_file_is_empty(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("   \n", encoding="utf-8")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        assert resolver.read_session_ingress_token() is None
+
+    def should_return_none_when_file_is_not_valid_utf8(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        token_file = tmp_path / "ingress-token"
+        token_file.write_bytes(b"\xff\xfe\x00token")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        assert resolver.read_session_ingress_token() is None
+
+    def should_pin_the_env_var_name_to_the_platform_contract(self) -> None:
+        assert INGRESS_TOKEN_FILE_ENV_VAR == "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
+
+
+class TestResolveAccessToken:
+    def should_use_ingress_token_when_credential_file_missing(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        missing_credentials = tmp_path / "absent.json"
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("ingress-token-value", encoding="utf-8")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        chosen_token = resolver.resolve_access_token(missing_credentials, local_now())
+        assert chosen_token == "ingress-token-value"
+
+    def should_prefer_credential_token_over_ingress_file(
+        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="credential-token"
+        )
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("ingress-token-value", encoding="utf-8")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        chosen_token = resolver.resolve_access_token(credentials_path, now)
+        assert chosen_token == "credential-token"
+
+    def should_return_none_when_ingress_file_missing(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        missing_credentials = tmp_path / "absent.json"
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(tmp_path / "absent-token"))
+        assert resolver.resolve_access_token(missing_credentials, local_now()) is None
+
+    def should_return_none_when_ingress_file_empty(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        missing_credentials = tmp_path / "absent.json"
+        token_file = tmp_path / "ingress-token"
+        token_file.write_text("   \n", encoding="utf-8")
+        monkeypatch.setenv(INGRESS_TOKEN_FILE_ENV_VAR, str(token_file))
+        assert resolver.resolve_access_token(missing_credentials, local_now()) is None
+
+    def should_return_none_when_env_unset_and_no_credential_file(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.delenv(INGRESS_TOKEN_FILE_ENV_VAR, raising=False)
+        missing_credentials = tmp_path / "absent.json"
+        assert resolver.resolve_access_token(missing_credentials, local_now()) is None
 
 
 class TestExtractUsageWindows:
@@ -232,12 +360,20 @@ class TestBuildPausePlan:
 
 
 class TestCommandLine:
-    def run_resolver(self, *arguments: str) -> subprocess.CompletedProcess[str]:
+    def run_resolver(
+        self, *arguments: str, ingress_token_file: 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
         return subprocess.run(
             [sys.executable, str(RESOLVER_PATH), *arguments],
             capture_output=True,
             text=True,
             check=False,
+            env=child_environment,
         )
 
     def should_resolve_duration_override_end_to_end(self) -> None:
@@ -264,6 +400,38 @@ class TestCommandLine:
         assert completed.returncode == 2
         resolved_payload = json.loads(completed.stdout)
         assert "error" in resolved_payload
+        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:
+        missing_credentials = tmp_path / "absent.json"
+        stale_ingress = tmp_path / "stale-ingress-token"
+        completed = self.run_resolver(
+            "--credentials-path",
+            str(missing_credentials),
+            ingress_token_file=str(stale_ingress),
+        )
+        assert completed.returncode == 2
+        resolved_payload = json.loads(completed.stdout)
+        assert str(stale_ingress) in resolved_payload["error"]
+
+    def should_report_ingress_env_var_set_but_empty_in_the_error(
+        self, tmp_path: Path
+    ) -> None:
+        missing_credentials = tmp_path / "absent.json"
+        completed = self.run_resolver(
+            "--credentials-path",
+            str(missing_credentials),
+            ingress_token_file="",
+        )
+        assert completed.returncode == 2
+        resolved_payload = json.loads(completed.stdout)
+        assert (
+            f"{INGRESS_TOKEN_FILE_ENV_VAR} set but empty"
+            in resolved_payload["error"]
+        )
 
     def should_reject_invalid_override_with_error_payload(self) -> None:
         completed = self.run_resolver("--override", "soon")

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

@@ -1,9 +1,9 @@
 """Constants for the usage-window resolver.
 
 Groups: the OAuth usage-endpoint probe, the CLI credential file keys, 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 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
@@ -21,6 +21,7 @@ ALL_CREDENTIALS_RELATIVE_PATH_PARTS = (".claude", ".credentials.json")
 CREDENTIALS_OAUTH_SECTION_KEY = "claudeAiOauth"
 CREDENTIALS_ACCESS_TOKEN_KEY = "accessToken"
 CREDENTIALS_EXPIRES_AT_KEY = "expiresAt"
+SESSION_INGRESS_TOKEN_FILE_ENV_VAR = "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
 MILLISECONDS_PER_SECOND = 1000
 
 FIVE_HOUR_BUCKET_KEY = "five_hour"

package/skills/verified-build/SKILL.md

@@ -1,15 +1,10 @@
 ---
 name: verified-build
 description: >-
-  Runs a code task through the two-phase verified workflow: scoped coder
-  agents write the changes (consulting the tool-less code-advisor when
-  stuck on a decision), then a fresh-context code-verifier agent re-derives
-  and runs every check itself. The verifier's fenced verdict is minted by
-  the verifier_verdict_minter hook and unlocks the verified_commit_gate for
-  git commit/push. Use for feature implementations, refactors, and bug
-  fixes that land behind verification. Triggers: 'verified build', 'run
-  this verified', 'two-phase build', 'build and verify', 'verified
-  implementation'.
+  Two-phase verified workflow: scoped coder agents write the changes, then a
+  fresh-context code-verifier re-runs every check. Use for implementations,
+  refactors, and bug fixes. Triggers: 'verified build', 'run this verified',
+  'two-phase build', 'build and verify', 'verified implementation'.
 ---
 
 # Verified Build

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

@@ -1,25 +0,0 @@
----
-name: team-advisor-refresh
-description: >-
-  Fired by the /team-advisor loop reminder about every 20 minutes to
-  re-assert the advisor discipline mid-run. A compressed restatement of
-  /team-advisor: orchestrate rather than execute, answer a blocked executor
-  with a plan, correction, or stop, and reuse warm agents before spawning new
-  ones. Triggers: '/team-advisor-refresh'.
----
-
-# Team Advisor Refresh
-
-1. **You are the advisor.** Orchestrate and hold the user conversation; spawn
-   executor subagents to do all the work — every code edit and build or test
-   run.
-2. **An executor blocked twice on the same thing?** Answer it with one signal
-   — a plan, a correction, or a stop — brief. Never take over the edit or the
-   tests yourself.
-3. **Resume before you spawn.** `SendMessage` an existing agent by name or
-   `agentId` to reuse its warm context; prefer that over a cold spawn.
-4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
-   subagent's context, so a clean context comes from a fresh spawn — never tell
-   an agent to compact.
-5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
-   mechanism needs each firing to queue the following one.