claude-dev-env 2.2.0 → 2.2.1

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -8,12 +8,19 @@ when that content violates a validator, rather than grading the whole branch.
 import json
 import subprocess
 import sys
+from collections import Counter
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 
-from .run_all_validators import main, run_validators_entrypoint_subprocess
+from .run_all_validators import (
+    ValidatorResult,
+    _scope_new_and_preexisting,
+    _violation_line_number,
+    main,
+    run_validators_entrypoint_subprocess,
+)
 
 CLEAN_PYTHON_SOURCE = (
     "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
@@ -26,7 +33,9 @@ VIOLATING_PYTHON_SOURCE = (
 
 
 def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
-    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+    return run_validators_entrypoint_subprocess(
+        ["--pre-tool-use"], stdin_text=json.dumps(payload)
+    )
 
 
 class TestPreToolUseGate:
@@ -73,7 +82,9 @@ class TestPreToolUseGate:
         assert completed.returncode == 0, completed.stderr
         assert "deny" not in completed.stdout
 
-    def test_edit_validates_reconstructed_post_edit_content(self, tmp_path: Path) -> None:
+    def test_edit_validates_reconstructed_post_edit_content(
+        self, tmp_path: Path
+    ) -> None:
         target_file = tmp_path / "calculate.py"
         target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
         completed = run_gate(
@@ -116,3 +127,212 @@ class TestCliModeRegression:
         captured = capsys.readouterr()
         assert exit_code == 1
         assert "PRE-PUSH VALIDATOR RESULTS" in captured.out
+
+
+def _over_long_function_source(function_name: str) -> str:
+    """Return a syntactically clean function whose only defect is exceeding 30 lines."""
+    body_lines = "".join("    running_total = running_total + 1\n" for _ in range(35))
+    return (
+        f"def {function_name}(running_total: int) -> int:\n"
+        f"{body_lines}"
+        "    return running_total\n"
+    )
+
+
+CLEAN_MARKER_FUNCTION = "def clean_marker() -> int:\n    return 1\n"
+CLEAN_MARKER_EDITED = (
+    "def clean_marker() -> int:\n    computed_value = 1\n    return computed_value\n"
+)
+MAGIC_VALUE_MARKER_FUNCTION = "def clean_marker() -> int:\n    return 199\n"
+PRE_EXISTING_VIOLATION_SOURCE = (
+    _over_long_function_source("over_long_function") + "\n" + CLEAN_MARKER_FUNCTION
+)
+MAGIC_VALUE_FUNCTION_SOURCE = "def compute_total() -> int:\n    return 199\n"
+RUFF_DIRTY_FUNCTION_SOURCE = (
+    "def compute_total() -> int:\n    unused_intermediate = 1\n    return 1\n"
+)
+
+
+class TestBaselineScopedGate:
+    def test_clean_edit_to_violating_file_is_allowed_with_warning(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(PRE_EXISTING_VIOLATION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": CLEAN_MARKER_FUNCTION,
+                    "new_string": CLEAN_MARKER_EDITED,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' not in completed.stdout
+        assert "Code Quality" in completed.stderr
+
+    def test_edit_introducing_new_violation_denies_naming_only_the_new_one(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(PRE_EXISTING_VIOLATION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": CLEAN_MARKER_FUNCTION,
+                    "new_string": MAGIC_VALUE_MARKER_FUNCTION,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+        assert "Code Quality" not in completed.stdout
+
+    def test_new_violation_in_clean_file_denies(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "clean_module.py"
+        target_file.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 1\n",
+                    "new_string": "    return 199\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_clean_edit_to_clean_file_is_allowed(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "clean_module.py"
+        target_file.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 1\n",
+                    "new_string": "    computed_value = 1\n    return computed_value\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_growing_a_function_with_existing_length_violation_is_allowed_with_warning(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(
+            _over_long_function_source("over_long_function"), encoding="utf-8"
+        )
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return running_total\n",
+                    "new_string": (
+                        "    running_total = running_total + 1\n"
+                        "    running_total = running_total + 1\n"
+                        "    return running_total\n"
+                    ),
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' not in completed.stdout
+        assert "Code Quality" in completed.stderr
+
+    def test_new_same_validator_violation_in_dirty_function_denies(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(MAGIC_VALUE_FUNCTION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 199\n",
+                    "new_string": "    threshold = 42\n    return 199 + threshold\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_new_module_scope_ruff_violation_with_dirty_function_denies(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(RUFF_DIRTY_FUNCTION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "def compute_total",
+                    "new_string": "import os\n\n\ndef compute_total",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "F401" in completed.stdout
+        assert "F841" not in completed.stdout
+
+
+class TestScopeNewAndPreexisting:
+    def test_failed_result_without_located_lines_is_treated_as_new(self) -> None:
+        summary_only_result = ValidatorResult(
+            name="Ruff", checks="37", passed=False, output="Found 1 error."
+        )
+
+        new_results, preexisting_results = _scope_new_and_preexisting(
+            [summary_only_result], "import os\n", Counter()
+        )
+
+        assert [each_result.name for each_result in new_results] == ["Ruff"]
+        assert preexisting_results == []
+
+
+class TestViolationLineNumber:
+    def test_ruff_line_col_prefix_returns_line_not_column(self) -> None:
+        ruff_shaped_line = "/pkg/legacy_module.py:37:5: F401 `os` imported but unused"
+
+        assert _violation_line_number(ruff_shaped_line) == 37
+
+    def test_windows_drive_prefix_returns_line(self) -> None:
+        windows_shaped_line = r"C:\repo\tmp\legacy_module.py:37:5: F401 unused import"
+
+        assert _violation_line_number(windows_shaped_line) == 37
+
+    def test_check_module_line_prefix_returns_line(self) -> None:
+        check_module_line = "/pkg/legacy_module.py:37: magic number 199"
+
+        assert _violation_line_number(check_module_line) == 37
+
+    def test_summary_line_without_location_returns_zero(self) -> None:
+        assert _violation_line_number("Found 3 errors.") == 0
+
+    def test_code_frame_line_quoting_colon_digits_returns_zero(self) -> None:
+        frame_line = '4 | message = "err:37: bad"'
+
+        assert _violation_line_number(frame_line) == 0
+
+    def test_code_frame_source_line_returns_zero(self) -> None:
+        assert _violation_line_number("17 | import os") == 0
+
+    def test_path_with_spaces_returns_line(self) -> None:
+        spaced_path_line = "/tmp/my dir/legacy module.py:37: magic number 199"
+
+        assert _violation_line_number(spaced_path_line) == 37

package/package.json

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

package/rules/CLAUDE.md

@@ -16,6 +16,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
 | `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |
+| `cleanup-command-forms.md` | Never use bash `rm` to clean up; use the PowerShell `Remove-Item` and `git worktree remove --force` forms the `destructive_command_blocker` hook never prompts on, and carry the rule into every subagent prompt |
 | `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
 | `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
 | `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |

package/rules/cleanup-command-forms.md

@@ -0,0 +1,23 @@
+# Cleanup Command Forms
+
+Never use bash `rm` in any form to clean up. The `destructive_command_blocker` hook watches every Bash-tool command and matches `rm -rf` (and the rest of the destructive patterns) as raw text. It allows an `rm` without a prompt only for a narrow set of shapes it can prove safe: an `rm` whose every target is an absolute path under the OS temp root, `/tmp`, `/temp`, or a worktrees directory — standalone, or in a chain whose other segments are plain reporting commands such as `echo` or `cat`; an `rm` run from an ephemeral working directory; and an `rm` whose every target sits inside `~/.claude`. It falls through to a permission prompt on anything outside that set: a `$`, `$(...)`, or backtick expansion whose value it cannot resolve, a target it cannot place in a safe directory, a glob basename, or a string-executing wrapper (`bash -c 'rm -rf …'`). In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Remove files with these forms, which the hook never prompts on:
+
+- **Scratch and probe files:** the PowerShell tool — `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`. The hook watches only the Bash tool, so a PowerShell removal never reaches it. A file left in the OS temp dir or `$CLAUDE_JOB_DIR/tmp` is ephemeral and needs no explicit removal.
+- **Worktrees:** `git worktree remove --force <path>`. This matches no destructive pattern.
+- **When bash `rm` is unavoidable:** one standalone `rm` command, an absolute literal path under the OS temp root or a worktrees directory, no chaining, no variables, no globs. The hook auto-allows this shape without a prompt.
+
+## Every subagent prompt carries the rule
+
+A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers — review lenses, fix agents, verifiers — copies this line into every subagent prompt it issues, so a grandchild cleaning up its own probe file uses an allowed form:
+
+> Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
+
+Prefer that a child leaves its scratch files in place for the parent to remove at teardown with `Remove-Item`.
+
+## Sibling rules
+
+- [`no-inline-destructive-literals`](no-inline-destructive-literals.md) — keep a destructive literal out of the Bash command string even when it rides only as data.
+- [`cleanup-temp-files`](cleanup-temp-files.md) — remove the scratch files a task created once the task is done.
+- [`windows-filesystem-safe`](windows-filesystem-safe.md) — the safe `rmtree` / `force_rmtree` patterns for read-only Windows files.

package/scripts/check.ps1

@@ -1,23 +1,25 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-    One-shot quality gate for the hooks package — runs ruff, mypy, and the
+    One-shot quality gate — runs ruff, hooks mypy, pr-loop mypy, and the
     blocking pytest suite from a single entry point.
 
 .DESCRIPTION
     Resolves paths relative to $PSScriptRoot so the script works from any CWD
     and from both the worktree (packages/claude-dev-env/scripts/check.ps1)
     and the installed runtime (~/.claude/scripts/check.ps1, after install.mjs
-    propagates this file). Each tool runs sequentially; the first non-zero
-    exit code is preserved as the script's exit code so CI/pre-commit can
-    short-circuit on the first failure.
+    propagates this file). Tools: ruff over hooks/, mypy over hooks blocking
+    and validators, mypy-pr-loop over _shared/pr-loop/scripts production
+    modules, and optional pytest over the blocking enforcer suite. Each tool
+    runs sequentially; the first non-zero exit code is preserved as the
+    script's exit code so CI/pre-commit can short-circuit on the first failure.
 
 .PARAMETER SkipTests
     Skip the pytest run. Useful during local iteration when you want only the
     static-analysis gates.
 
 .PARAMETER SkipMypy
-    Skip the mypy run.
+    Skip both mypy runs (hooks mypy and mypy-pr-loop).
 
 .PARAMETER SkipRuff
     Skip the ruff run.
@@ -25,7 +27,7 @@
 .OUTPUTS
     Per-tool status lines on stdout. Final summary line:
         CHECK: OK
-        CHECK: FAILED tools=ruff,mypy,pytest
+        CHECK: FAILED tools=ruff,mypy,mypy-pr-loop,pytest
 #>
 [CmdletBinding()]
 param(
@@ -38,6 +40,7 @@ $ErrorActionPreference = 'Stop'
 
 $hooksRoot = Resolve-Path (Join-Path $PSScriptRoot '..' 'hooks')
 $blockingRoot = Join-Path $hooksRoot 'blocking'
+$prLoopScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'pr-loop' 'scripts')
 
 $failedTools = @()
 $firstNonZeroExitCode = 0
@@ -82,6 +85,29 @@ if (-not $SkipMypy) {
             Pop-Location
         }
     }
+
+    Invoke-Tool -Label 'mypy-pr-loop' -Action {
+        Push-Location $prLoopScriptsRoot
+        try {
+            mypy --config-file (Join-Path $prLoopScriptsRoot 'pyproject.toml') `
+                _claude_permissions_common.py `
+                code_rules_gate.py `
+                copilot_quota.py `
+                fix_hookspath.py `
+                grant_project_claude_permissions.py `
+                post_audit_thread.py `
+                preflight_self_heal.py `
+                preflight.py `
+                reviewer_availability.py `
+                reviews_disabled.py `
+                revoke_project_claude_permissions.py `
+                terminology_sweep.py `
+                code_rules_gate_parts `
+                pr_loop_shared_constants
+        } finally {
+            Pop-Location
+        }
+    }
 }
 
 if (-not $SkipTests) {

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 (