multi-claude-cli 0.9.0__tar.gz → 0.9.1__tar.gz

{multi_claude_cli-0.9.0 → multi_claude_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.9.0
+Version: 0.9.1
 Summary: Run several Claude Code accounts side by side: separate CLAUDE_CONFIG_DIR directories, launchers, proxies, environment variables and arguments.
 License: MIT
 Project-URL: Homepage, https://github.com/jakoes-wu/multi-claude
@@ -37,7 +37,7 @@ Dynamic: license-file
 
 Use several [Claude Code](https://code.claude.com/docs) accounts on one machine, at the same time. Each account keeps its own login, settings and history and, if you like, its own proxy. No more logging out and in again.
 
-It never changes or copies your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan; `list --offline` skips that.
+It never copies or exports your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan (renewing the token first if it has expired); `list --offline` skips all of that.
 
 ```sh
 claude-work        # Claude Code with your work account
@@ -64,8 +64,8 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Features
 
-- **Your login stays yours** — logins are never written, copied, exported or refreshed. One command reads one: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on. The token stays in memory and goes only to `api.anthropic.com`, through that account's proxy. `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
-- **One kind of network request, nothing else** — the plan lookup of `list` (one request per account) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
+- **Your login stays yours** — logins are never copied or exported. One command touches them: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on, and when that token has expired it renews it the way Claude Code does and saves the new one in the same place. Tokens stay in memory and go only to Anthropic (`api.anthropic.com`, and `platform.claude.com` for a renewal), through that account's proxy. `list --no-refresh` never writes, `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
+- **Only `list` goes online** — its plan lookup (one request per account, plus one to renew an expired token) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
 - **Leaves your shell alone** — when `PATH` needs a change, it prints the line to add instead of editing `~/.zshrc` or `~/.bashrc`.
 - **Changes only what you ask** — it writes its own configuration and state, the launchers, account directories (including the VS Code data that `code` keeps in `<root>/.apps`) and shared links. A Claude Code settings file is changed only by `statusline install` (the file you name, with a backup) and `add --config-from` (the new account's `settings.json`).
 - **Migrate the default account** — move your existing `~/.claude` into the account root without logging out. `claude` keeps working exactly as before.
@@ -78,7 +78,7 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Prerequisites
 
-**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups of `list`, sent to Anthropic.
+**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups and token renewals of `list`, sent to Anthropic.
 
 **Your computer.**
 
@@ -319,15 +319,17 @@ work:
 NAME   LOGIN     PLAN      BILLING      PROXY                  SHARED  5H         7D       LAST USED  STATUS
 work   keychain  max (5x)  stripe       http://127.0.0.1:7890  no      23% 14:00  41% Fri  5m ago     ok
 home   keychain  pro       apple        inherit                no      -          -        2d ago     ok
-old    keychain  expired   -            inherit                no      -          -        9d ago     ok
+old    keychain  token expired  -       inherit                no      -          -        9d ago     ok
 ```
 
 `PLAN` and `BILLING` are not cached values: every `list` asks Anthropic (`GET https://api.anthropic.com/api/oauth/profile`, the request Claude Code itself makes) with the account's own access token. `PLAN` is the subscription — `pro`, `max (5x)`, `max (20x)`, `team`, `enterprise`. `BILLING` is where the subscription is paid: `stripe` (claude.ai), `apple` (App Store), `google-play`, `aws-marketplace` and so on.
 
 - The request uses the account's proxy setting, exactly like its launcher: the configured proxy, the proxy variables of your shell for `inherit`, none for `off`. If a proxy is configured and fails, the lookup fails; it never falls back to a direct connection. Only `http://` proxies work for the lookup.
-- `expired` means the access token has run out. Tokens last a few hours and multi-claude never refreshes them (refreshing would compete with running sessions): start `claude-NAME` once and run `list` again. `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- Access tokens last a few hours. When one has expired, `list` renews it first: it takes the same lock as Claude Code (`.oauth_refresh.lock` in the account directory), posts the refresh token to `https://platform.claude.com/v1/oauth/token`, and saves the new tokens where the old ones were, keeping everything else in the login untouched. A running Claude session picks the new token up by itself. If another process has just renewed the token, `list` uses that result and writes nothing; if another process holds the lock, `list` does not wait and shows `token expired` this time. This follows what Claude Code 2.1.295 does; it is not a documented interface.
+- `token expired` means the access token has run out and could not be renewed; the subscription itself is not affected. The reason is on stderr (`token refresh failed for work: lock_busy`). Start `claude-NAME` once and run `list` again; when the reason is `refresh_rejected` or `no_refresh_token`, log in again with `multi-claude login NAME`. `list --no-refresh` never renews and never writes to a login.
+- `-` means the account has no OAuth login, and `rejected` that the server refused the token.
 - `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
-- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object; scripts should use it instead of parsing the table. The lookup adds about a second, at most 15.
+- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
 
 ### Handing a session over to another account
 
@@ -463,7 +465,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-It never writes, copies, exports, uploads, refreshes or backs up a login. One command reads one: `list` takes each account's access token to ask Anthropic for the account's plan (see [Plan and billing](#plan-and-billing)); the token stays in memory and is sent only to `api.anthropic.com`. `list --offline` does not read it. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+It never copies, exports, uploads or backs up a login. One command touches one: `list` takes each account's access token to ask Anthropic for the account's plan, and renews the token when it has expired, saving the new one where the old one was (see [Plan and billing](#plan-and-billing)). Tokens stay in memory and are sent only to Anthropic. `list --no-refresh` never writes and `list --offline` does not read. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
 
 ## Reference
 
@@ -483,7 +485,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--offline` skips the plan lookup (no token read, no network). |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

{multi_claude_cli-0.9.0 → multi_claude_cli-0.9.1}/README.md

@@ -10,7 +10,7 @@
 
 Use several [Claude Code](https://code.claude.com/docs) accounts on one machine, at the same time. Each account keeps its own login, settings and history and, if you like, its own proxy. No more logging out and in again.
 
-It never changes or copies your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan; `list --offline` skips that.
+It never copies or exports your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan (renewing the token first if it has expired); `list --offline` skips all of that.
 
 ```sh
 claude-work        # Claude Code with your work account
@@ -37,8 +37,8 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Features
 
-- **Your login stays yours** — logins are never written, copied, exported or refreshed. One command reads one: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on. The token stays in memory and goes only to `api.anthropic.com`, through that account's proxy. `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
-- **One kind of network request, nothing else** — the plan lookup of `list` (one request per account) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
+- **Your login stays yours** — logins are never copied or exported. One command touches them: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on, and when that token has expired it renews it the way Claude Code does and saves the new one in the same place. Tokens stay in memory and go only to Anthropic (`api.anthropic.com`, and `platform.claude.com` for a renewal), through that account's proxy. `list --no-refresh` never writes, `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
+- **Only `list` goes online** — its plan lookup (one request per account, plus one to renew an expired token) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
 - **Leaves your shell alone** — when `PATH` needs a change, it prints the line to add instead of editing `~/.zshrc` or `~/.bashrc`.
 - **Changes only what you ask** — it writes its own configuration and state, the launchers, account directories (including the VS Code data that `code` keeps in `<root>/.apps`) and shared links. A Claude Code settings file is changed only by `statusline install` (the file you name, with a backup) and `add --config-from` (the new account's `settings.json`).
 - **Migrate the default account** — move your existing `~/.claude` into the account root without logging out. `claude` keeps working exactly as before.
@@ -51,7 +51,7 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Prerequisites
 
-**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups of `list`, sent to Anthropic.
+**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups and token renewals of `list`, sent to Anthropic.
 
 **Your computer.**
 
@@ -292,15 +292,17 @@ work:
 NAME   LOGIN     PLAN      BILLING      PROXY                  SHARED  5H         7D       LAST USED  STATUS
 work   keychain  max (5x)  stripe       http://127.0.0.1:7890  no      23% 14:00  41% Fri  5m ago     ok
 home   keychain  pro       apple        inherit                no      -          -        2d ago     ok
-old    keychain  expired   -            inherit                no      -          -        9d ago     ok
+old    keychain  token expired  -       inherit                no      -          -        9d ago     ok
 ```
 
 `PLAN` and `BILLING` are not cached values: every `list` asks Anthropic (`GET https://api.anthropic.com/api/oauth/profile`, the request Claude Code itself makes) with the account's own access token. `PLAN` is the subscription — `pro`, `max (5x)`, `max (20x)`, `team`, `enterprise`. `BILLING` is where the subscription is paid: `stripe` (claude.ai), `apple` (App Store), `google-play`, `aws-marketplace` and so on.
 
 - The request uses the account's proxy setting, exactly like its launcher: the configured proxy, the proxy variables of your shell for `inherit`, none for `off`. If a proxy is configured and fails, the lookup fails; it never falls back to a direct connection. Only `http://` proxies work for the lookup.
-- `expired` means the access token has run out. Tokens last a few hours and multi-claude never refreshes them (refreshing would compete with running sessions): start `claude-NAME` once and run `list` again. `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- Access tokens last a few hours. When one has expired, `list` renews it first: it takes the same lock as Claude Code (`.oauth_refresh.lock` in the account directory), posts the refresh token to `https://platform.claude.com/v1/oauth/token`, and saves the new tokens where the old ones were, keeping everything else in the login untouched. A running Claude session picks the new token up by itself. If another process has just renewed the token, `list` uses that result and writes nothing; if another process holds the lock, `list` does not wait and shows `token expired` this time. This follows what Claude Code 2.1.295 does; it is not a documented interface.
+- `token expired` means the access token has run out and could not be renewed; the subscription itself is not affected. The reason is on stderr (`token refresh failed for work: lock_busy`). Start `claude-NAME` once and run `list` again; when the reason is `refresh_rejected` or `no_refresh_token`, log in again with `multi-claude login NAME`. `list --no-refresh` never renews and never writes to a login.
+- `-` means the account has no OAuth login, and `rejected` that the server refused the token.
 - `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
-- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object; scripts should use it instead of parsing the table. The lookup adds about a second, at most 15.
+- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
 
 ### Handing a session over to another account
 
@@ -436,7 +438,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-It never writes, copies, exports, uploads, refreshes or backs up a login. One command reads one: `list` takes each account's access token to ask Anthropic for the account's plan (see [Plan and billing](#plan-and-billing)); the token stays in memory and is sent only to `api.anthropic.com`. `list --offline` does not read it. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+It never copies, exports, uploads or backs up a login. One command touches one: `list` takes each account's access token to ask Anthropic for the account's plan, and renews the token when it has expired, saving the new one where the old one was (see [Plan and billing](#plan-and-billing)). Tokens stay in memory and are sent only to Anthropic. `list --no-refresh` never writes and `list --offline` does not read. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
 
 ## Reference
 
@@ -456,7 +458,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--offline` skips the plan lookup (no token read, no network). |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

{multi_claude_cli-0.9.0 → multi_claude_cli-0.9.1}/src/multi_claude/__init__.py

@@ -1,3 +1,3 @@
 """multi-claude：管理多个 Claude Code 账号的配置目录、启动命令、代理与启动参数。"""
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"

{multi_claude_cli-0.9.0 → multi_claude_cli-0.9.1}/src/multi_claude/cli.py

@@ -19,7 +19,7 @@ from datetime import datetime, timedelta, timezone
 from typing import List, Optional, Tuple
 
 from . import (__version__, accounts, bundle, completion, doctor, history, hook, identity, launcher, migrate,
-               plan, platform, restore, routes, sessions, shellpath, statusline, usage)
+               plan, platform, refresh, restore, routes, sessions, shellpath, statusline, usage)
 from .actions import LOG_PREFIX, error, info, warn
 from .config import (DEFAULT_SHARED_DIR, DEFAULT_SHARED_ITEMS, IDENTITY_DEFAULT, IDENTITY_DIR, Account, Config, ConfigError, RouteRule,
                      is_unshareable, load_config, normalize_proxy, parse_config, validate_env_key, validate_name,
@@ -173,6 +173,9 @@ def build_parser() -> argparse.ArgumentParser:
                            help="show every field, the global settings and the keychain details")
     list_mode.add_argument("--json", action="store_true", help="print machine-readable JSON (includes usage)")
     list_mode.add_argument("--names", action="store_true", help="print only the account names, one per line")
+    p_list.add_argument("--no-refresh", action="store_true",
+                        help="do not renew an expired access token (never write to the login); "
+                             "such accounts show 'token expired'")
     p_list.add_argument("--offline", action="store_true",
                         help="skip the plan lookup: do not read access tokens and do not connect to the network")
 
@@ -400,7 +403,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             warn(notice)
         # list 与 usage 只读：不加写锁，迁移未完成时也放行。
         if args.command == "list":
-            return cmd_list(verbose=args.verbose, as_json=args.json, names_only=args.names, offline=args.offline)
+            return cmd_list(verbose=args.verbose, as_json=args.json, names_only=args.names, offline=args.offline,
+                            refresh_tokens=not args.no_refresh)
         if args.command == "usage":
             if args.history:
                 return cmd_usage_history(args.name, args.days, args.by or "day", args.json)
@@ -1263,8 +1267,10 @@ def _checked_proxy(value: str) -> str:
         raise UsageError(str(exc))
 
 
-def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = False, offline: bool = False) -> int:
-    """列出账号。除 --names 与 --offline 外，会读各账号的访问令牌并向服务端查询套餐（方案 feature-live-plan）。"""
+def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = False, offline: bool = False,
+             refresh_tokens: bool = True) -> int:
+    """列出账号。除 --names 与 --offline 外，会读各账号的访问令牌并向服务端查询套餐（方案 feature-live-plan）；
+    访问令牌过期时先刷新并写回凭据，refresh_tokens 为假时不刷新（方案 feature-token-refresh）。"""
     config, exists = load_config()
     if names_only:
         # 给补全脚本用：只输出名称，不输出任何告警。
@@ -1276,7 +1282,8 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
         if variable in os.environ:
             warn("{} is set; launchers do not change it, even with proxy off".format(variable))
     # 套餐只查一次，表格与 JSON 共用；None 表示本次不查（--offline 或还没有配置）。
-    plans = None if offline or not exists else plan.query_all(config, os.environ, datetime.now(timezone.utc))
+    plans = None if offline or not exists else plan.query_all(config, os.environ, datetime.now(timezone.utc),
+                                                             allow_refresh=refresh_tokens)
     if as_json:
         _print_json(_list_data(config, exists, plans))
         if exists:
@@ -1336,20 +1343,27 @@ def _plan_cells(plans: Optional[dict], name: str) -> tuple:
 
 
 def _report_plan_problems(plans: Optional[dict]) -> None:
-    """套餐查询的失败与过期提示，打到 stderr；不影响表格、STATUS 列与退出码。"""
+    """套餐查询与令牌刷新的失败提示，打到 stderr；不影响表格、STATUS 列与退出码。"""
     if plans is None:
         return
     expired = []
     for name, result in plans.items():
+        if result.refresh == refresh.SAVE_FAILED:
+            # 新令牌只用了这一次、没存下来：旧的刷新令牌多半已作废，下次启动可能要重新登录。
+            error("the renewed login of {0} could not be saved; if claude-{0} asks you to log in, "
+                  "run multi-claude login {0}".format(name))
         if result.status == plan.STATUS_ERROR:
             warn(plan.failure_text(name, result))
         elif result.status == plan.STATUS_EXPIRED:
             expired.append(name)
+            if result.refresh is not None:
+                hint = "; run multi-claude login {}".format(name) if result.refresh in refresh.NEEDS_LOGIN else ""
+                warn("token refresh failed for {}: {}{}".format(name, result.refresh, hint))
     if expired:
-        # multi-claude 不刷新令牌：让 Claude Code 自己续期，再查一次即可。
         # 走 stderr 而不是 info()：info() 写 stdout，会混进 --json 的输出。
-        print("{} expired: start {} once to renew the login, then run list again".format(
-            LOG_PREFIX, ", ".join("claude-" + name for name in expired)), file=sys.stderr)
+        print("{} token expired: the access token ran out, the subscription is not affected; start {} once, "
+              "then run list again".format(LOG_PREFIX, ", ".join("claude-" + name for name in expired)),
+              file=sys.stderr)
 
 
 def _print_brief_list(config: Config, plans: Optional[dict] = None) -> int:

{multi_claude_cli-0.9.0 → multi_claude_cli-0.9.1}/src/multi_claude/identity.py

@@ -6,10 +6,13 @@ Claude Code 在 macOS 上把登录凭据存进钥匙串，服务名由配置目
 
 - `probe()`：只查询凭据是否存在。钥匙串调用 `security find-generic-password -a <账户> -s <服务名>`，
   不带 -w / -g，只看退出码。
-- `read_oauth_token()`：读出访问令牌，供 `list` 向服务端查询套餐（plan.py 是唯一调用方）。
-  钥匙串调用带 -w 的同一条命令。令牌只留在内存里，不写入文件、日志或任何输出。
+- `read_oauth_token()` / `read_credentials()`：读出访问令牌或整份凭据，供 `list` 向服务端查询套餐
+  （调用方只有 plan.py 与 refresh.py）。钥匙串调用带 -w 的同一条命令。内容只留在内存里，
+  不写入日志或任何输出。
 
-任何情况下都不写入、复制或删除凭据。整个工具只有这两处调用 `security`，测试会断言它们收到的参数。
+唯一的写入是 `write_credentials()`：`list` 发现访问令牌过期、用刷新令牌换到新令牌后，把新令牌写回
+原来的位置（方案 feature-token-refresh；refresh.py 是唯一调用方）。除此之外不写入、不复制、不删除凭据。
+调用 `security` 的地方只有本模块，测试会断言它收到的参数。
 """
 
 import hashlib
@@ -24,6 +27,7 @@ import unicodedata
 from typing import NamedTuple, Optional, Tuple
 
 from .config import IDENTITY_DEFAULT
+from .fsutil import atomic_write
 
 SERVICE_BASE = "Claude Code-credentials"
 CREDENTIALS_FILE = ".credentials.json"
@@ -62,7 +66,8 @@ def keychain_account() -> str:
             user = pwd.getpwuid(os.getuid()).pw_name
         except KeyError:
             user = ""
-    if not _KEYCHAIN_ACCOUNT_PATTERN.match(user):
+    # fullmatch：`$` 会放过尾部换行，而账户名现在会拼进 `security -i` 的命令行
+    if not _KEYCHAIN_ACCOUNT_PATTERN.fullmatch(user):
         return "claude-code-user"
     return user
 
@@ -174,11 +179,22 @@ def _parse_credentials(state: str, text: Optional[str]) -> Tuple[str, Optional[O
         return TOKEN_UNREADABLE, None
     if not isinstance(data, dict):
         return TOKEN_UNREADABLE, None
-    oauth = data.get("claudeAiOauth")
-    access_token = oauth.get("accessToken") if isinstance(oauth, dict) else None
+    token = token_of(data)
+    return (TOKEN_OK, token) if token is not None else (TOKEN_NONE, None)
+
+
+def is_token(value: object) -> bool:
+    """value 是否是能放进 HTTP 请求头的令牌串。"""
     # fullmatch 而不是 match：`$` 会放过尾部换行
-    if not isinstance(access_token, str) or not _TOKEN_PATTERN.fullmatch(access_token):
-        return TOKEN_NONE, None
+    return isinstance(value, str) and _TOKEN_PATTERN.fullmatch(value) is not None
+
+
+def token_of(document: dict) -> Optional[OAuthToken]:
+    """从凭据 JSON 对象里取访问令牌；没有可用的访问令牌时返回 None。"""
+    oauth = document.get("claudeAiOauth")
+    access_token = oauth.get("accessToken") if isinstance(oauth, dict) else None
+    if not is_token(access_token):
+        return None
     expires_at = oauth.get("expiresAt")
     # bool 是 int 的子类，要先排除
     # JSON 里的 1e999 会解析成 inf，取整会抛异常：非有限值同样当作“没有过期时刻”
@@ -186,4 +202,84 @@ def _parse_credentials(state: str, text: Optional[str]) -> Tuple[str, Optional[O
     if isinstance(expires_at, bool) or not isinstance(expires_at, (int, float)) \
             or (isinstance(expires_at, float) and not math.isfinite(expires_at)):
         expires_at = None
-    return TOKEN_OK, OAuthToken(TOKEN_OK, access_token, None if expires_at is None else int(expires_at))
+    return OAuthToken(TOKEN_OK, access_token, None if expires_at is None else int(expires_at))
+
+
+class Credentials(NamedTuple):
+    state: str
+    # claudeAiOauth 是从哪里读到的：LOGIN_KEYCHAIN 或 LOGIN_FILE；state 不是 TOKEN_OK 时为空串
+    source: str
+    # 该来源的完整 JSON 对象（含 claudeAiOauth 以外的键，如 mcpOAuth）；写回时必须整份带上
+    document: Optional[dict]
+
+
+def read_credentials(identity: str, account_dir: str) -> Credentials:
+    """读出含 OAuth 登录的那份凭据，以及它的来源。来源顺序与 read_oauth_token() 相同。
+
+    与 read_oauth_token() 的区别：只要求有 claudeAiOauth 对象，不要求访问令牌可用，
+    因为刷新要处理的正是访问令牌已经失效的凭据。
+    """
+    sources = []
+    if sys.platform == "darwin":
+        sources.append((LOGIN_KEYCHAIN, _read_keychain_secret(service_name(identity, account_dir))))
+    sources.append((LOGIN_FILE, _read_credentials_file(credentials_file(account_dir))))
+    unreadable = False
+    for source, (state, text) in sources:
+        if text is None:
+            unreadable = unreadable or state == TOKEN_UNREADABLE
+            continue
+        try:
+            data = json.loads(text)
+        except ValueError:
+            data = None
+        if not isinstance(data, dict):
+            unreadable = True
+        elif isinstance(data.get("claudeAiOauth"), dict):
+            return Credentials(TOKEN_OK, source, data)
+    return Credentials(TOKEN_UNREADABLE if unreadable else TOKEN_NONE, "", None)
+
+
+# `security -i` 从 stdin 读一行命令的长度上限，取自 Claude Code；超过时它改用命令行参数，这里照做。
+_SECURITY_STDIN_LIMIT = 4032
+
+
+def write_credentials(identity: str, account_dir: str, source: str, document: dict) -> bool:
+    """把整份凭据写回 source 指定的位置，返回是否成功。全工具唯一写凭据的入口。
+
+    两种写法都是整体替换：钥匙串条目由 security 原子更新，文件用临时文件加 rename，
+    任何时刻被打断，凭据要么是旧的、要么是完整的新的。
+    调用方必须先确认 document 来自同一来源的最新读取结果，只改了令牌相关字段。
+    """
+    text = json.dumps(document, separators=(",", ":"))
+    if source == LOGIN_KEYCHAIN:
+        return _write_keychain_secret(service_name(identity, account_dir), text)
+    if source == LOGIN_FILE:
+        try:
+            # 凭据文件是软链时写到它指向的文件：直接替换会把软链换成普通文件，原文件反而没更新
+            atomic_write(os.path.realpath(credentials_file(account_dir)), text, 0o600)
+        except OSError:
+            return False
+        return True
+    return False
+
+
+def _write_keychain_secret(service: str, text: str) -> bool:
+    """与 Claude Code 写钥匙串的方式相同：内容转成十六进制，经 stdin 交给 `security -i`。
+
+    走 stdin 是为了不让内容出现在进程列表里。命令行超过上限时 security 读不完整，
+    只能改用参数（Claude Code 也是这样做的），这时十六进制内容在本机进程列表里短暂可见。
+    """
+    payload = text.encode("utf-8").hex()
+    account = keychain_account()
+    line = 'add-generic-password -U -a "{}" -s "{}" -X "{}"\n'.format(account, service, payload)
+    try:
+        if len(line) <= _SECURITY_STDIN_LIMIT:
+            proc = subprocess.run(["security", "-i"], input=line.encode("utf-8"),
+                                  stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=10)
+        else:
+            proc = subprocess.run(["security", "add-generic-password", "-U", "-a", account, "-s", service,
+                                   "-X", payload], stdin=subprocess.DEVNULL,
+                                  stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0