claude-dev-env 8.82.0 → 8.83.0

package/scripts/account_broker_support.py

@@ -26,7 +26,7 @@ else:
 import codex_account_choice
 import codex_account_meters
 from claude_account_profile import default_profile_home, validate_profile_name
-from claude_chain_usage import WeeklyUtilizationProbeError, probe_account_meters
+from claude_chain_usage import ClaudeSignedOutError, WeeklyUtilizationProbeError, probe_account_meters
 from dev_env_scripts_constants.account_broker_constants import (
     ALL_BATCH_FILE_EXTENSIONS,
     ALL_CLAUDE_BINARY_CANDIDATE_RELATIVE_PARTS,
@@ -41,6 +41,7 @@ from dev_env_scripts_constants.account_broker_constants import (
     CMD_SHELL_METACHARACTERS,
     Decision,
     JobOutcome,
+    ALL_LOGIN_REFRESH_ENVIRONMENT,
     LOGIN_REFRESH_TIMEOUT_SECONDS,
     METER_READ_ATTEMPTS,
     Meters,
@@ -253,7 +254,7 @@ def refresh_claude_login(account_home: Path) -> bool:
     claude_path = resolve_claude_path()
     if claude_path is None:
         return False
-    refresh_environment = {**os.environ, CLAUDE_CONFIG_DIR_ENV_VAR: str(account_home)}
+    refresh_environment = {**os.environ, **ALL_LOGIN_REFRESH_ENVIRONMENT, CLAUDE_CONFIG_DIR_ENV_VAR: str(account_home)}
     try:
         subprocess.run(
             [str(claude_path), *ALL_LOGIN_REFRESH_ARGUMENTS],
@@ -325,7 +326,7 @@ def read_meters_with_backoff(read_meters: Callable[[Account], Meters | None], ac
     Returns:
         The meters from the first read that succeeds, or None with the last
         failure text once every attempt failed. A missing Codex executable
-        fails at once, without a retry.
+        or a signed-out Claude account fails at once, without a retry.
     """
     unread_reason = None
     for each_attempt in range(METER_READ_ATTEMPTS):
@@ -333,7 +334,7 @@ def read_meters_with_backoff(read_meters: Callable[[Account], Meters | None], ac
             time.sleep(meter_read_delay_seconds(each_attempt))
         try:
             return read_meters(account), None
-        except codex_account_meters.CodexExecutableNotFoundError as error:
+        except (codex_account_meters.CodexExecutableNotFoundError, ClaudeSignedOutError) as error:
             return None, str(error)
         except (
             codex_account_meters.CodexMeterUnreadError,

package/scripts/ci/install-playtest.mjs

@@ -54,6 +54,56 @@ export const PRE_TOOL_USE_EVENT_NAME = 'PreToolUse';
 export const SESSION_START_HOOK_SCRIPT_NAME = 'working_style_prompt.py';
 export const BASH_HOOK_SCRIPT_NAME = 'bash_pre_tool_use_dispatcher.py';
 export const BASH_MATCHER = 'Bash';
+export const USER_PROMPT_SUBMIT_EVENT_NAME = 'UserPromptSubmit';
+export const DEEPEN_HOOK_SCRIPT_NAME = 'deepen_first_prompt.py';
+export const NESTED_HOOK_SCRIPT_NAME = 'nested_project_hooks.py';
+export const DEEPEN_MARKER = 'CDE_DEEPEN:v1';
+export const DEEPEN_AGENT_MARKER = 'CDE_DEEPEN_AGENT';
+export const DEEPEN_STAGE_NAME = 'deepen_first_prompt';
+export const DEEPEN_SKIP_STAGE_NAME = 'deepen_skips';
+export const DEEPEN_REWRITE_STAGE_NAME = 'deepen_mod_text';
+export const DEEPEN_NESTED_STAGE_NAME = 'deepen_nested_home';
+export const DEEPEN_CLOUD_GAP_STAGE_NAME = 'deepen_cloud_gaps';
+export const DEEPEN_STUB_REWRITE = [
+    'Omitted: ship contrast tokens with the theme.',
+    'Source: src/settings/theme.ts',
+    'Methods: existing token file and a visual check.',
+    'Proof: screenshot of the settings page in dark mode.',
+].join('\n');
+export const CLAUDE_SUBAGENT_PROMPT_PREFIX = (
+    'Before any other work, invoke the poteto-mode skill with the Skill tool. '
+    + 'Every prompt you write for a subagent opens with the same instruction.'
+);
+export const CLOUD_GAP_EVIDENCE = {
+    cursorCloud: {
+        doc: 'https://cursor.com/docs/hooks',
+        quotes: [
+            'User-level hooks (`~/.cursor/hooks.json`) are not available in cloud agents. Cloud agent VMs don\'t have access to your local home directory configuration.',
+            'sessionStart: Deferred while cloud agents can still start in a read-only environment. Hooks don\'t load there, so a cloud sessionStart would fire too late (after the first write) rather than at true session start.',
+            'beforeSubmitPrompt output is continue and user_message only.',
+        ],
+        path: 'the deepen skill under ~/.cursor/skills',
+    },
+    codexCloud: {
+        doc: 'https://learn.chatgpt.com/docs/hooks',
+        quotes: [
+            'Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and SessionEnd MCP hooks are not supported with cloud orchestration, even when tools execute locally.',
+        ],
+    },
+    claudeUserPromptSubmit: {
+        doc: 'https://code.claude.com/docs/en/hooks',
+        quotes: [
+            'UserPromptSubmit: can\'t replace the prompt; it only injects additionalContext alongside it',
+        ],
+    },
+    claudePromptSubmitMod: {
+        doc: 'https://code.claude.com/docs/en/plugins/mods/events',
+        quotes: [
+            'Rewrite the prompt. The transcript and your prompt history show the new text. next({ ...e, text: newText })',
+            'A cloud session: Yes, for a plugin that reaches the cloud session. This package still keeps the Python hook as the cloud fallback because mods that replace settings hooks stay off when CLAUDE_CODE_REMOTE is true.',
+        ],
+    },
+};
 
 export const SESSION_START_PAYLOAD = {
     hook_event_name: SESSION_START_EVENT_NAME,
@@ -146,14 +196,14 @@ export function selectHookCommand(allCommands, scriptName) {
  * @param {object} payload The hook payload written to standard input.
  * @returns {{status: number | null, stdout: string, stderr: string}} The hook's result.
  */
-export function runInstalledHook(command, scratchHome, payload) {
+export function runInstalledHook(command, scratchHome, payload, extraEnvironment = {}) {
     const hookProcess = spawnSync(command, {
         shell: true,
         input: JSON.stringify(payload),
         encoding: 'utf8',
         cwd: scratchHome,
         timeout: HOOK_TIMEOUT_MILLISECONDS,
-        env: scratchHomeEnvironment(scratchHome),
+        env: { ...scratchHomeEnvironment(scratchHome), ...extraEnvironment },
     });
     return {
         status: hookProcess.status,
@@ -227,10 +277,275 @@ function runSessionStartStage(settingsPath, scratchHome, evidenceDirectory) {
     if (typeof envelope.additionalContext !== 'string' || envelope.additionalContext.length === 0) {
         throw new Error('The SessionStart envelope carries no additionalContext');
     }
+    if (envelope.additionalContext.includes(DEEPEN_MARKER)) {
+        throw new Error('The SessionStart envelope repeated first-task deepen text');
+    }
     const evidencePath = writeEvidence(evidenceDirectory, SESSION_START_STAGE_NAME, JSON.stringify(envelope));
     reportStage(SESSION_START_STAGE_NAME, evidencePath);
 }
 
+function userPromptPayload(prompt, transcriptPath) {
+    const payload = {
+        hook_event_name: USER_PROMPT_SUBMIT_EVENT_NAME,
+        prompt,
+        session_id: 'playtest-session',
+    };
+    if (transcriptPath) payload.transcript_path = transcriptPath;
+    return payload;
+}
+
+function deepenHookEnvironment(extraEnvironment = {}) {
+    return {
+        CDE_DEEPEN_REWRITE: DEEPEN_STUB_REWRITE,
+        ...extraEnvironment,
+    };
+}
+
+function parseJsonDecision(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) return { decision: 'silent' };
+    return JSON.parse(trimmed);
+}
+
+function runDeepenFirstTaskStage(settingsPath, scratchHome, evidenceDirectory) {
+    const command = selectHookCommand(
+        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
+        DEEPEN_HOOK_SCRIPT_NAME,
+    );
+    const transcriptPath = join(evidenceDirectory, 'first-task.jsonl');
+    const extraEnvironment = deepenHookEnvironment();
+    const envelopeResult = runInstalledHook(
+        command,
+        scratchHome,
+        userPromptPayload('Add dark mode to the settings page', transcriptPath),
+        extraEnvironment,
+    );
+    const envelope = readEnvelope(envelopeResult.stdout, USER_PROMPT_SUBMIT_EVENT_NAME);
+    if (!String(envelope.additionalContext || '').includes(DEEPEN_MARKER)) {
+        throw new Error('The UserPromptSubmit envelope carries no deepen marker');
+    }
+    if (!String(envelope.additionalContext).includes('src/settings/theme.ts')) {
+        throw new Error('The UserPromptSubmit envelope omitted the stub source');
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        DEEPEN_STAGE_NAME,
+        JSON.stringify(envelope),
+    );
+    reportStage(DEEPEN_STAGE_NAME, evidencePath);
+    return { command, transcriptPath };
+}
+
+function runDeepenRewriteStage(command, scratchHome, evidenceDirectory) {
+    const transcriptPath = join(evidenceDirectory, 'mod-text.jsonl');
+    const hookResult = runInstalledHook(
+        command,
+        scratchHome,
+        userPromptPayload('Add dark mode to the settings page', transcriptPath),
+        deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'rewrite' }),
+    );
+    const printed = hookResult.stdout;
+    if (!printed.startsWith(DEEPEN_MARKER)) {
+        throw new Error(`The rewrite output did not start with ${DEEPEN_MARKER}`);
+    }
+    if (printed.includes('hookSpecificOutput')) {
+        throw new Error('The Claude mod rewrite printed a command-hook envelope');
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        DEEPEN_REWRITE_STAGE_NAME,
+        JSON.stringify({ stdout: printed }),
+    );
+    reportStage(DEEPEN_REWRITE_STAGE_NAME, evidencePath);
+}
+
+function runDeepenSkipStage(command, scratchHome, evidenceDirectory, firstTranscriptPath) {
+    const jsonEnvironment = deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'json' });
+    const cases = [
+        {
+            name: 'thanks',
+            payload: userPromptPayload('thanks', join(evidenceDirectory, 'thanks.jsonl')),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'trivial' },
+        },
+        {
+            name: 'slash',
+            payload: userPromptPayload('/sr-loop', join(evidenceDirectory, 'slash.jsonl')),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'slash-command' },
+        },
+        {
+            name: 'spawn',
+            payload: userPromptPayload(
+                `${CLAUDE_SUBAGENT_PROMPT_PREFIX}\n\nReply leaf.`,
+                join(evidenceDirectory, 'spawn.jsonl'),
+            ),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'spawn-rewrite' },
+        },
+        {
+            name: 'skip-flag',
+            payload: userPromptPayload('Add dark mode to the settings page', join(evidenceDirectory, 'skip-flag.jsonl')),
+            extraEnvironment: deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'json', CDE_SKIP_DEEPEN: '1' }),
+            expected: { decision: 'skip', reason: 'skip-flag' },
+        },
+        {
+            name: 'later-turn',
+            payload: userPromptPayload('and also the billing page', firstTranscriptPath),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'later-turn' },
+        },
+        {
+            name: 'marker',
+            payload: userPromptPayload(`${DEEPEN_MARKER}\n\nDo the job.`, join(evidenceDirectory, 'marker.jsonl')),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'marker-present' },
+        },
+        {
+            name: 'loop',
+            payload: userPromptPayload('/loop until tests pass', join(evidenceDirectory, 'loop.jsonl')),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'loop-or-helper' },
+        },
+        {
+            name: 'deepen-agent',
+            payload: userPromptPayload(
+                `${DEEPEN_AGENT_MARKER}\nAnswer the four deepening questions.`,
+                join(evidenceDirectory, 'agent.jsonl'),
+            ),
+            extraEnvironment: jsonEnvironment,
+            expected: { decision: 'skip', reason: 'deepen-agent' },
+        },
+    ];
+    const results = [];
+    for (const eachCase of cases) {
+        const hookResult = runInstalledHook(
+            command,
+            scratchHome,
+            eachCase.payload,
+            eachCase.extraEnvironment,
+        );
+        const decision = parseJsonDecision(hookResult.stdout);
+        if (decision.decision !== eachCase.expected.decision || decision.reason !== eachCase.expected.reason) {
+            throw new Error(
+                `Skip ${eachCase.name} returned ${JSON.stringify(decision)} expected ${JSON.stringify(eachCase.expected)}`,
+            );
+        }
+        results.push({ name: eachCase.name, decision });
+    }
+    const silentThanks = runInstalledHook(
+        command,
+        scratchHome,
+        userPromptPayload('thanks', join(evidenceDirectory, 'thanks-silent.jsonl')),
+        deepenHookEnvironment(),
+    );
+    if (silentThanks.stdout.trim() !== '') {
+        throw new Error('A skipped prompt printed command-hook output');
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        DEEPEN_SKIP_STAGE_NAME,
+        JSON.stringify({ results, silentThanks: silentThanks.stdout }),
+    );
+    reportStage(DEEPEN_SKIP_STAGE_NAME, evidencePath);
+}
+
+function runDeepenNestedStage(settingsPath, scratchHome, evidenceDirectory) {
+    const nestedCommand = selectHookCommand(
+        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
+        NESTED_HOOK_SCRIPT_NAME,
+    );
+    const deepenCommand = selectHookCommand(
+        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
+        DEEPEN_HOOK_SCRIPT_NAME,
+    );
+    const sessionDirectory = join(evidenceDirectory, 'nested-session');
+    const checkoutDirectory = join(sessionDirectory, 'alpha');
+    mkdirSync(join(checkoutDirectory, '.git'), { recursive: true });
+    mkdirSync(join(checkoutDirectory, '.claude'), { recursive: true });
+    writeFileSync(
+        join(checkoutDirectory, '.claude', 'settings.json'),
+        `${JSON.stringify({
+            hooks: {
+                UserPromptSubmit: [
+                    {
+                        matcher: '',
+                        hooks: [{ type: 'command', command: deepenCommand, timeout: 10 }],
+                    },
+                ],
+            },
+        }, null, 2)}\n`,
+    );
+    const hookResult = spawnSync(nestedCommand, {
+        shell: true,
+        input: JSON.stringify(userPromptPayload(
+            'Add dark mode to the settings page',
+            join(evidenceDirectory, 'nested.jsonl'),
+        )),
+        encoding: 'utf8',
+        cwd: sessionDirectory,
+        timeout: HOOK_TIMEOUT_MILLISECONDS,
+        env: {
+            ...scratchHomeEnvironment(scratchHome),
+            ...deepenHookEnvironment(),
+            CLAUDE_PROJECT_DIR: sessionDirectory,
+        },
+    });
+    const envelope = readEnvelope(hookResult.stdout, USER_PROMPT_SUBMIT_EVENT_NAME);
+    if (!String(envelope.additionalContext || '').includes(DEEPEN_MARKER)) {
+        throw new Error('The nested home-folder session carried no deepen marker');
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        DEEPEN_NESTED_STAGE_NAME,
+        JSON.stringify(envelope),
+    );
+    reportStage(DEEPEN_NESTED_STAGE_NAME, evidencePath);
+}
+
+function runDeepenInstallSurfaceStage(scratchHome, evidenceDirectory) {
+    const settingsPath = join(scratchHome, SETTINGS_RELATIVE_PATH);
+    const userPromptCommands = hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME);
+    if (!userPromptCommands.some((each) => each.command.includes(DEEPEN_HOOK_SCRIPT_NAME))) {
+        throw new Error('The installed Claude settings declare no deepen_first_prompt.py');
+    }
+    const codexHooksPath = join(scratchHome, '.codex', 'hooks.json');
+    const codexHooks = JSON.parse(readFileSync(codexHooksPath, 'utf8'));
+    const codexUserPrompt = JSON.stringify(codexHooks.hooks?.UserPromptSubmit ?? []);
+    if (!codexUserPrompt.includes(DEEPEN_HOOK_SCRIPT_NAME)) {
+        throw new Error('The installed Codex hooks declare no UserPromptSubmit deepen_first_prompt.py');
+    }
+    const cursorSkillPath = join(scratchHome, '.cursor', 'skills', 'deepen', 'SKILL.md');
+    if (!existsSync(cursorSkillPath)) {
+        throw new Error(`The install wrote no ${cursorSkillPath}`);
+    }
+    const codexAgentsPath = join(scratchHome, '.codex', 'AGENTS.md');
+    const codexAgentsText = existsSync(codexAgentsPath) ? readFileSync(codexAgentsPath, 'utf8') : '';
+    if (!codexAgentsText.includes('<!-- claude-dev-env deepen: start -->')) {
+        throw new Error(`The install wrote no deepen block into ${codexAgentsPath}`);
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        'deepen_install_surfaces',
+        JSON.stringify({
+            claudeUserPromptSubmit: userPromptCommands.map((each) => each.command),
+            codexUserPromptSubmit: codexHooks.hooks.UserPromptSubmit,
+            cursorSkillPath,
+            codexAgentsPath,
+        }),
+    );
+    reportStage('deepen_install_surfaces', evidencePath);
+}
+
+function runDeepenCloudGapStage(evidenceDirectory) {
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        DEEPEN_CLOUD_GAP_STAGE_NAME,
+        JSON.stringify(CLOUD_GAP_EVIDENCE),
+    );
+    reportStage(DEEPEN_CLOUD_GAP_STAGE_NAME, evidencePath);
+}
+
 function runBlockingStage(settingsPath, scratchHome, evidenceDirectory) {
     const command = selectHookCommand(
         hookCommandsForEvent(settingsPath, PRE_TOOL_USE_EVENT_NAME),
@@ -274,6 +589,18 @@ export function runPlaytest(argv) {
         runSessionStartStage(settingsPath, scratchHome, evidenceDirectory);
         stageName = BLOCKING_STAGE_NAME;
         runBlockingStage(settingsPath, scratchHome, evidenceDirectory);
+        stageName = 'deepen_install_surfaces';
+        runDeepenInstallSurfaceStage(scratchHome, evidenceDirectory);
+        stageName = DEEPEN_STAGE_NAME;
+        const deepen = runDeepenFirstTaskStage(settingsPath, scratchHome, evidenceDirectory);
+        stageName = DEEPEN_REWRITE_STAGE_NAME;
+        runDeepenRewriteStage(deepen.command, scratchHome, evidenceDirectory);
+        stageName = DEEPEN_SKIP_STAGE_NAME;
+        runDeepenSkipStage(deepen.command, scratchHome, evidenceDirectory, deepen.transcriptPath);
+        stageName = DEEPEN_NESTED_STAGE_NAME;
+        runDeepenNestedStage(settingsPath, scratchHome, evidenceDirectory);
+        stageName = DEEPEN_CLOUD_GAP_STAGE_NAME;
+        runDeepenCloudGapStage(evidenceDirectory);
     } catch (error) {
         reportFailure(stageName, error instanceof Error ? error.message : String(error));
         return 1;

package/scripts/ci/install-playtest.test.mjs

@@ -30,6 +30,12 @@ test('the driver reads an envelope from every stage of a fresh install, and repo
         assert.match(greenRun.stdout, /\[PASS\] playtest install .* sha256=[0-9a-f]{64}/);
         assert.match(greenRun.stdout, /\[PASS\] playtest session_start_hook .* sha256=[0-9a-f]{64}/);
         assert.match(greenRun.stdout, /\[PASS\] playtest blocking_hook .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_install_surfaces .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_first_prompt .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_mod_text .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_skips .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_nested_home .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_cloud_gaps .* sha256=[0-9a-f]{64}/);
         const blockingEnvelope = JSON.parse(readFileSync(join(evidenceDirectory, 'blocking_hook.json'), 'utf8'));
         assert.equal(Object.hasOwn(blockingEnvelope, 'permissionDecision'), false);
         assert.ok(

package/scripts/claude_chain_usage.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import http.client
 import importlib.util
+import json
 import sys
 import urllib.error
 from dataclasses import dataclass
@@ -13,6 +14,8 @@ from types import ModuleType
 from typing import Callable
 
 from dev_env_scripts_constants.claude_chain_usage_constants import (
+    CREDENTIALS_OAUTH_SECTION_KEY,
+    CREDENTIALS_REFRESH_TOKEN_KEY,
     NO_ACCESS_TOKEN_ERROR_TEMPLATE,
     RESOLVE_USAGE_WINDOW_FILENAME,
     RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE,
@@ -29,6 +32,10 @@ class WeeklyUtilizationProbeError(Exception):
     """Raised when an account's usage meters cannot be measured."""
 
 
+class ClaudeSignedOutError(WeeklyUtilizationProbeError):
+    """Raised when an account has no usable token and no way to get one, so a retry cannot help."""
+
+
 def _usage_pause_scripts_directory(module_file: Path) -> Path:
     """Return the usage-pause scripts directory beside this scripts tree.
 
@@ -111,6 +118,24 @@ class AccountUsageMeters:
     weekly_resets_at: datetime | None
 
 
+def _holds_refresh_token(credentials_path: Path) -> bool:
+    """Report whether a credential file holds a refresh token the CLI can renew a login from.
+
+    Args:
+        credentials_path: The account's CLI credential file.
+
+    Returns:
+        True when the file's OAuth section carries a non-empty refresh token.
+    """
+    try:
+        credentials_payload = json.loads(credentials_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    oauth_section = credentials_payload.get(CREDENTIALS_OAUTH_SECTION_KEY) if isinstance(credentials_payload, dict) else None
+    refresh_token = oauth_section.get(CREDENTIALS_REFRESH_TOKEN_KEY) if isinstance(oauth_section, dict) else None
+    return isinstance(refresh_token, str) and bool(refresh_token)
+
+
 def _read_access_token(
     usage_window_resolver: ModuleType,
     credentials_path: Path,
@@ -123,6 +148,7 @@ def _read_access_token(
 
         credential file holds a token                ->  that token
         token expired, refresh_login saves a new one ->  the new token
+        no token and no refresh token (signed out)   ->  no refresh_login call
         no token, the session's own credential path  ->  the session ingress token
         no token, another account's credential path  ->  None
 
@@ -142,7 +168,7 @@ def _read_access_token(
     file_token = usage_window_resolver.read_oauth_access_token(credentials_path, now)
     if file_token is not None:
         return file_token
-    if refresh_login is not None and credentials_path.is_file():
+    if refresh_login is not None and _holds_refresh_token(credentials_path):
         refresh_login(credentials_path.parent)
         refreshed_token = usage_window_resolver.read_oauth_access_token(credentials_path, datetime.now().astimezone())
         if refreshed_token is not None:
@@ -162,7 +188,7 @@ def _fetch_account_usage_payload(
     try:
         access_token = _read_access_token(usage_window_resolver, credentials_path, now, refresh_login)
         if access_token is None:
-            raise WeeklyUtilizationProbeError(
+            raise ClaudeSignedOutError(
                 NO_ACCESS_TOKEN_ERROR_TEMPLATE.format(credentials_path=credentials_path)
             )
         return usage_window_resolver._fetch_usage_payload(access_token)

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -68,7 +68,33 @@ ALL_CLAUDE_BINARY_CANDIDATE_RELATIVE_PARTS: tuple[tuple[str, ...], ...] = (
     (".local", "bin", "claude.exe"),
     (".local", "bin", "claude"),
 )
-ALL_LOGIN_REFRESH_ARGUMENTS: tuple[str, ...] = ("-p", "ok", "--model", "haiku")
+ALL_LOGIN_REFRESH_ARGUMENTS: tuple[str, ...] = (
+    "-p",
+    "ok",
+    "--model",
+    "haiku",
+    "--setting-sources",
+    "local",
+    "--settings",
+    '{"enabledPlugins": {}, "autoMemoryEnabled": false}',
+    "--strict-mcp-config",
+    "--mcp-config",
+    '{"mcpServers": {}}',
+    "--no-session-persistence",
+    "--disable-slash-commands",
+    "--tools",
+    "",
+    "--max-turns",
+    "1",
+)
+ALL_LOGIN_REFRESH_ENVIRONMENT: dict[str, str] = {
+    "CLAUDE_CODE_DISABLE_CLAUDE_MDS": "1",
+    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "DISABLE_TELEMETRY": "1",
+    "DISABLE_ERROR_REPORTING": "1",
+    "DISABLE_AUTOUPDATER": "1",
+}
 LOGIN_REFRESH_TIMEOUT_SECONDS = 120.0
 ALL_PARENT_CLAUDE_SESSION_VARIABLES: frozenset[str] = frozenset({
     "CLAUDE_CODE_SESSION_ID",

package/scripts/dev_env_scripts_constants/claude_chain_usage_constants.py

@@ -42,6 +42,12 @@ JSON_ERROR_KEY: str = "error"
 CLI_CONFIG_PATH_FLAG: str = "--config-path"
 """CLI flag that overrides the chain configuration file path."""
 
+CREDENTIALS_OAUTH_SECTION_KEY: str = "claudeAiOauth"
+"""Credential file key holding the CLI's OAuth login."""
+
+CREDENTIALS_REFRESH_TOKEN_KEY: str = "refreshToken"
+"""OAuth section key holding the token the CLI renews a login from; empty when signed out."""
+
 NO_ACCESS_TOKEN_ERROR_TEMPLATE: str = (
     "no usable bearer token from the OAuth credential file at {credentials_path}"
 )

package/scripts/test_account_broker_support.py

@@ -348,6 +348,22 @@ def test_should_cap_the_meter_read_delay(monkeypatch: pytest.MonkeyPatch, tmp_pa
     assert all_delays == [1.0, 2.0, 4.0, 8.0, 8.0]
 
 
+def test_should_read_a_signed_out_claude_account_once(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    all_delays = _recorded_sleeps(monkeypatch)
+    all_reads: list[Account] = []
+
+    def signed_out_reader(account: Account) -> Meters:
+        all_reads.append(account)
+        raise support.ClaudeSignedOutError("no usable bearer token")
+
+    meters, unread_reason = support.read_meters_with_backoff(signed_out_reader, Account(Product.CLAUDE, "main", tmp_path))
+
+    assert meters is None
+    assert unread_reason == "no usable bearer token"
+    assert len(all_reads) == 1
+    assert all_delays == []
+
+
 def test_should_cache_account_reading_under_injected_state_path(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -604,19 +620,35 @@ def test_should_match_order_names_to_an_account_named_by_its_windows_launcher_pa
 
 
 def test_should_run_the_cli_against_the_account_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    all_calls: list[tuple[list[str], str]] = []
+    all_calls: list[tuple[list[str], dict[str, str]]] = []
 
     def fake_run(command: list[str], **keyword_arguments: object) -> subprocess.CompletedProcess[bytes]:
         environment = keyword_arguments["env"]
         assert isinstance(environment, dict)
-        all_calls.append((command, environment["CLAUDE_CONFIG_DIR"]))
+        all_calls.append((command, environment))
         return subprocess.CompletedProcess(command, 0)
 
     monkeypatch.setattr(support, "resolve_claude_path", lambda: Path("claude"))
     monkeypatch.setattr(support.subprocess, "run", fake_run)
 
     assert support.refresh_claude_login(tmp_path) is True
-    assert all_calls == [(["claude", "-p", "ok", "--model", "haiku"], str(tmp_path))]
+    [(command, environment)] = all_calls
+    assert command[:5] == ["claude", "-p", "ok", "--model", "haiku"]
+    assert command[command.index("--setting-sources") + 1] == "local"
+    assert json.loads(command[command.index("--settings") + 1]) == {"enabledPlugins": {}, "autoMemoryEnabled": False}
+    assert "--strict-mcp-config" in command
+    assert json.loads(command[command.index("--mcp-config") + 1]) == {"mcpServers": {}}
+    assert "--no-session-persistence" in command
+    assert "--disable-slash-commands" in command
+    assert command[command.index("--tools") + 1] == ""
+    assert command[command.index("--max-turns") + 1] == "1"
+    assert environment["CLAUDE_CONFIG_DIR"] == str(tmp_path)
+    assert environment["CLAUDE_CODE_DISABLE_CLAUDE_MDS"] == "1"
+    assert environment["CLAUDE_CODE_DISABLE_AUTO_MEMORY"] == "1"
+    assert environment["CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"] == "1"
+    assert environment["DISABLE_TELEMETRY"] == "1"
+    assert environment["DISABLE_ERROR_REPORTING"] == "1"
+    assert environment["DISABLE_AUTOUPDATER"] == "1"
 
 
 def test_should_skip_the_refresh_without_a_cli(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:

package/scripts/test_claude_chain_usage.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import subprocess
 import sys
 import urllib.error
@@ -212,11 +213,18 @@ def _expiring_resolver(all_tokens: list[str | None], all_fetched_tokens: list[st
     return Resolver()
 
 
+def _write_credentials(credentials_path: Path, refresh_token: str) -> None:
+    credentials_path.write_text(
+        json.dumps({"claudeAiOauth": {"accessToken": "", "refreshToken": refresh_token, "expiresAt": 0}}),
+        encoding="utf-8",
+    )
+
+
 def test_should_refresh_an_expired_login_and_read_the_meter(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     account_home = tmp_path / "ev"
     account_home.mkdir()
     credentials_path = account_home / ".credentials.json"
-    credentials_path.write_text("{}", encoding="utf-8")
+    _write_credentials(credentials_path, "refresh-value")
     all_refreshed_homes: list[Path] = []
     all_fetched_tokens: list[str] = []
     monkeypatch.setattr(usage, "_load_resolve_usage_window_module", lambda: _expiring_resolver([None, "fresh-token"], all_fetched_tokens))
@@ -230,8 +238,23 @@ def test_should_refresh_an_expired_login_and_read_the_meter(monkeypatch: pytest.
 
 def test_should_report_no_token_when_the_refresh_saves_none(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     credentials_path = tmp_path / ".credentials.json"
-    credentials_path.write_text("{}", encoding="utf-8")
+    _write_credentials(credentials_path, "refresh-value")
     monkeypatch.setattr(usage, "_load_resolve_usage_window_module", lambda: _expiring_resolver([None, None], []))
 
-    with pytest.raises(usage.WeeklyUtilizationProbeError, match="bearer token"):
+    with pytest.raises(usage.ClaudeSignedOutError, match="bearer token"):
         usage.probe_account_meters(credentials_path, lambda home: True)
+
+
+@pytest.mark.parametrize("credentials_text", ["{}", '{"claudeAiOauth": {"accessToken": "", "refreshToken": "", "expiresAt": 0}}', "not json"])
+def test_should_skip_the_refresh_for_a_signed_out_account(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, credentials_text: str
+) -> None:
+    credentials_path = tmp_path / ".credentials.json"
+    credentials_path.write_text(credentials_text, encoding="utf-8")
+    all_refreshed_homes: list[Path] = []
+    monkeypatch.setattr(usage, "_load_resolve_usage_window_module", lambda: _expiring_resolver([None], []))
+
+    with pytest.raises(usage.ClaudeSignedOutError, match="bearer token"):
+        usage.probe_account_meters(credentials_path, all_refreshed_homes.append)
+
+    assert all_refreshed_homes == []