@leeguoo/wrangler-accounts 1.2.0 → 1.3.0

package/README.md

@@ -74,15 +74,47 @@ wrangler-accounts exec <name> -- <cmd> [args]   # one command
 wrangler-accounts login <name>                  # isolated OAuth login
 wrangler-accounts default [name | --unset]      # manage persistent default
 wrangler-accounts whoami [--profile <name>]     # show resolved identity
-wrangler-accounts list
+wrangler-accounts list                          # fast table (name/status/expires/identity)
+wrangler-accounts list --deep                   # authoritative check via wrangler whoami
+wrangler-accounts list --json                   # structured output for scripts
 wrangler-accounts status
 wrangler-accounts save <name>                   # snapshot current Wrangler config
 wrangler-accounts sync <name>                   # refresh a profile from current login
 wrangler-accounts sync-default                  # refresh the default profile
 wrangler-accounts remove <name>
 wrangler-accounts gc [--older-than 1h]          # clean stale shadow HOMEs
+-v, --version                                   # print version
 ```
 
+### `list` output
+
+Fast default (no network calls — read from saved `config.toml` only):
+
+```
+Default: work
+
+  NAME            STATUS  EXPIRES              IDENTITY
+* work            valid   in 47m (2026-04-10)  work@example.com / 0123456789abcdef0123456789abcdef
+  personal        valid   in 53m (2026-04-10)  me@example.com / fedcba9876543210fedcba9876543210
+
+Legend: * = default profile, EXPIRED = access token past expiration_time (wrangler may still auto-refresh)
+        STATUS is derived from the saved file only. For a live check that runs 'wrangler whoami' against Cloudflare,
+        pass --deep (slower, makes network calls).
+```
+
+Authoritative `--deep` check (spawns `wrangler whoami` in a shadow HOME per profile, ~1s each, network required):
+
+```
+[wrangler-accounts] running deep check (wrangler whoami) for 2 profile(s)...
+  NAME            STATUS  EXPIRES              VERIFIED                                     IDENTITY
+* work            valid   in 47m (2026-04-10)  ✓ ok                                         work@example.com / ...
+  personal        valid   in 53m (2026-04-10)  ✗ not logged in (refresh token may be revoked) me@example.com / ...
+```
+
+**When to use `--deep`**: when you actually need to know whether a profile still works. The default fast check only reads the saved `expiration_time`, which can lie in both directions — it can't tell you if Cloudflare has revoked the refresh token, and it flags fine profiles as `EXPIRED` just because their access token is past its 1-hour lifetime (wrangler auto-refreshes those transparently).
+
+The `--json` output includes the same fields as the table plus raw `expirationTime`, `isDefault`, `isActive`, and (with `--deep`) `verified`, `verifyError`, and `liveIdentity`.
+
 ## Profile resolution order
 
 When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved in this order:
@@ -114,7 +146,9 @@ When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved
     --backup            Backup current config on use (default)
     --no-backup         Disable backup on use
     --unset             With 'default': clear the persistent default
+    --deep, --verify    With 'list': run wrangler whoami per profile for live verification
     --older-than <dur>  With 'gc': age threshold (e.g. 1h, 30m, 7d)
+-v, -V, --version       Print version
 -h, --help              Show help
 ```
 
@@ -130,10 +164,28 @@ Inside an isolated session, these are automatically set for the child process:
 - `HOME` — the shadow HOME
 - `WRANGLER_PROFILE` / `WRANGLER_ACCOUNT` — current profile name (useful for shell prompt integration)
 - `WRANGLER_ACCOUNT_REAL_HOME` — path to your real home (escape hatch)
-- `WRANGLER_REGISTRY_PATH`, `WRANGLER_CACHE_DIR`, `WRANGLER_LOG_PATH` — pointed back at real HOME so Miniflare dev registry, workerd cache, and debug logs are shared across profiles
+- `WRANGLER_CACHE_DIR` — **per-profile**, points at `<profilesDir>/<name>/cache/`. Holds wrangler's `wrangler-account.json` (selected account ID), `pages-config-cache.json`, etc. Isolating this is critical: see "What is and isn't isolated" below.
+- `WRANGLER_REGISTRY_PATH`, `WRANGLER_LOG_PATH` — pointed at real HOME so Miniflare dev registry and debug logs are shared across profiles (cross-profile dev worker discovery is intentional)
 - `CLOUDFLARED_PATH` — set when `cloudflared` is on your PATH
 - `WRANGLER_SEND_METRICS=false`
 
+## What is and isn't isolated
+
+`wrangler-accounts` isolates the things that determine **which account a wrangler command targets**, but deliberately shares some state for performance and ergonomics. Know the boundary:
+
+| State | Location | Isolated? |
+|---|---|---|
+| OAuth credentials (`config.toml`, refresh token) | shadow `$HOME/.wrangler/config/default.toml` → symlink to per-profile file | ✅ per profile |
+| Account-id cache (`wrangler-account.json`) | `WRANGLER_CACHE_DIR` = `<profilesDir>/<name>/cache/` | ✅ per profile |
+| Pages config cache | same as above | ✅ per profile |
+| Miniflare dev registry | `WRANGLER_REGISTRY_PATH` = `$HOME/.wrangler/registry` | ❌ **shared** (intentional — local dev workers discover each other across profiles) |
+| Wrangler debug logs | `WRANGLER_LOG_PATH` = `$HOME/.wrangler/logs` | ❌ **shared** (append-only) |
+| Project-local state (`./.wrangler/state/`, `./node_modules/.cache/wrangler`) | inside the project directory | ❌ **shared at project level** — same project from two profiles uses the same project-local state. If you hit a "wrong account" symptom, clearing `./.wrangler/state/` is a good first step. |
+| `cloudflared` binary cache | `~/.wrangler/cloudflared/` or `$CLOUDFLARED_PATH` | ❌ shared (binary, not account-scoped) |
+| Shell history, `.npmrc`, `.gitconfig`, `.ssh/` etc. | symlinked through to real `$HOME` | ❌ shared by design (so `exec` subshells feel like a normal terminal) |
+
+> **Why this matters**: in 1.2.1 and earlier, `WRANGLER_CACHE_DIR` was pointed at real `$HOME/.wrangler/cache`, which meant `wrangler-account.json` was shared across profiles. Profile A's OAuth token could end up paired with profile B's cached account ID, causing wrangler to write resources to the wrong account *silently*. Fixed in 1.2.2 by per-profile `WRANGLER_CACHE_DIR`. Upgrade if you're on ≤1.2.1.
+
 ## Breaking changes in 1.0
 
 - **`-p` is now `--profile`** (was `--profiles` in 0.1.x). Use the long form `--profiles <path>` to specify the profiles directory.
@@ -162,10 +214,76 @@ The profiles directory defaults to:
 - Saved OAuth sessions can expire. If a profile is expired, running it will stop and tell you to run `wrangler-accounts login <name>` again.
 - Backups from the deprecated `use` command are hidden from `list` and `status` unless you pass `--include-backups`.
 
-## Discoverability (SEO / GEO / AI search)
+## FAQ
+
+### How do I use Cloudflare Wrangler with multiple accounts?
+
+`wrangler` itself only supports one OAuth login at a time — running `wrangler login` overwrites `~/.wrangler/config/default.toml`, forcing you to re-login every time you switch accounts. `wrangler-accounts` saves each login as a named profile and runs `wrangler` inside a per-invocation **shadow HOME**, so different shells can use different Cloudflare accounts in parallel.
+
+```bash
+npm i -g @leeguoo/wrangler-accounts
+wrangler-accounts login work
+wrangler-accounts login personal
+wrangler-accounts --profile work deploy
+wrangler-accounts --profile personal tail my-worker
+```
+
+### How do I switch between Cloudflare Workers accounts without logging out?
+
+Use `wrangler-accounts --profile <name>` for a single command, or `wrangler-accounts default <name>` to set a persistent default. Neither touches your existing `~/.wrangler/config/default.toml`; profiles live in their own directory.
+
+### Can I run `wrangler dev` on one Cloudflare account while deploying to another?
+
+Yes. That's the whole point of the shadow HOME isolation — each shell gets its own temporary HOME with the profile's OAuth config, so two invocations never share state.
+
+```bash
+# terminal 1
+wrangler-accounts --profile work tail my-worker --format pretty
+
+# terminal 2
+wrangler-accounts --profile personal dev
+```
+
+### How do I use Wrangler with multiple accounts in CI?
+
+**Don't use `wrangler-accounts` in CI.** Use native env vars — `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` — with plain `wrangler`. That's what Cloudflare designed wrangler for; `wrangler-accounts` is a local developer convenience for juggling OAuth sessions on your workstation.
+
+### Is this like `aws-vault` / `aws --profile` but for Cloudflare?
+
+Yes. `wrangler-accounts` is to Cloudflare Wrangler what `aws --profile` and `aws-vault exec` are to the AWS CLI: named profiles, per-invocation isolation, subshell mode, AWS-style resolution order (`--profile` > `$WRANGLER_PROFILE` > persistent default). Unlike AWS CLI, `wrangler` has no native `--profile` flag, so `wrangler-accounts` sits in front of `wrangler` and sets up an isolated `HOME` per invocation.
+
+### How do I know if a saved profile still works?
+
+`wrangler-accounts list` shows a fast table with STATUS (derived from the saved `expiration_time`), but that can miss revoked refresh tokens. For an authoritative check, run:
+
+```bash
+wrangler-accounts list --deep
+```
+
+This spawns `wrangler whoami` inside each profile's shadow HOME and reports whether Cloudflare actually accepts the credentials.
+
+### I get "Not logged in" even though I just ran `wrangler login`
+
+If you used plain `wrangler login`, it wrote to your real `~/.wrangler/config/default.toml`. Capture that as a named profile before it gets overwritten:
+
+```bash
+wrangler-accounts save work
+```
+
+Or start fresh with `wrangler-accounts login work`, which does the OAuth flow inside an isolated shadow HOME and writes directly into the profile directory.
+
+## Discoverability
+
+Project: Cloudflare Wrangler multi-account manager — save and switch between multiple Cloudflare Workers OAuth logins without re-authenticating each time.
+
+**Search keywords**: cloudflare wrangler multi account, wrangler multiple accounts, cloudflare workers switch account, wrangler profile manager, wrangler login profiles, cloudflare account switcher, wrangler --profile, AWS-style profile for wrangler, aws-vault for cloudflare, wrangler oauth multi account, cloudflare workers different accounts, per-invocation isolation, shadow home, wrangler account management CLI.
+
+**AI agent keywords**: agent skill, skills.sh, Claude Code skill, Cursor skill, Codex skill, Gemini CLI skill — see "Install as an AI agent skill" above.
 
-Cloudflare Wrangler multi-account switcher for global teams.
-Keywords: Cloudflare Workers account manager, Wrangler login profiles, multi-account, account switcher, AWS-style profile, per-invocation isolation, OAuth profile management.
+Related tools / alternatives:
+- [AWS CLI `--profile`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) — same concept for AWS, natively supported
+- [aws-vault](https://github.com/99designs/aws-vault) — OAuth-safe AWS profile wrapper that inspired the `exec` design here
+- [direnv](https://direnv.net/) — directory-based env switching (orthogonal, can be combined)
 
 ## Shell completion (zsh)
 

package/bin/wrangler-accounts.js

@@ -442,16 +442,13 @@ function main() {
       const session = readSessionState(cfgPath);
       const meta = readMeta(profileDir);
       const identity = getMetaIdentity(meta);
-      let status;
-      if (session.expired === true) status = "expired";
-      else if (session.expired === false) status = "valid";
-      else status = "unknown";
       return {
         name,
         isDefault: name === defaultName,
         isActive: name === activeName,
-        status,
+        status: session.effective, // 'valid' | 'refreshable' | 'expired' | 'unknown'
         expirationTime: session.expirationTime,
+        hasRefreshToken: session.hasRefreshToken,
         identity,
         verified: null,
         verifyError: null,
@@ -528,6 +525,7 @@ function main() {
       name: e.name,
       status:
         e.status === "expired" ? "EXPIRED"
+        : e.status === "refreshable" ? "valid*"
         : e.status === "valid" ? "valid"
         : "unknown",
       expires: formatExpiry(e.expirationTime),
@@ -563,17 +561,23 @@ function main() {
     console.log();
     if (opts.deep) {
       console.log(
-        "Legend: * = default profile, VERIFIED ✓ = wrangler whoami succeeded in shadow HOME, ✗ = authoritative failure",
+        "Legend: * = default profile | STATUS valid = access token fresh | valid* = access token expired but refresh_token will auto-refresh",
+      );
+      console.log(
+        "        EXPIRED = access token expired and no refresh_token, must 'login <name>' again",
+      );
+      console.log(
+        "        VERIFIED ✓ = 'wrangler whoami' succeeded in shadow HOME (authoritative) | ✗ = failed",
       );
     } else {
       console.log(
-        "Legend: * = default profile, EXPIRED = access token past expiration_time (wrangler may still auto-refresh)",
+        "Legend: * = default profile | STATUS valid = access token fresh | valid* = access token expired but refresh_token will auto-refresh",
       );
       console.log(
-        "        STATUS is derived from the saved file only. For a live check that runs 'wrangler whoami' against Cloudflare,",
+        "        EXPIRED = access token expired and no refresh_token, must 'login <name>' again | unknown = no expiration_time saved",
       );
       console.log(
-        "        pass --deep (slower, makes network calls).",
+        "        STATUS is file-only. For a live check against Cloudflare, pass --deep (slower, makes network calls).",
       );
     }
     return;
@@ -706,33 +710,47 @@ function main() {
     const shadowWranglerConfig = path.join(shadow, ".wrangler", "config");
     fs.mkdirSync(shadowWranglerConfig, { recursive: true });
 
+    // Pre-create the profile dir so per-profile cache lands in the right
+    // place even though config.toml doesn't exist yet (login will write
+    // it). This makes WRANGLER_CACHE_DIR isolated from the very first
+    // command, including the login flow itself. We remember whether the
+    // dir existed before so we can clean it up if login fails.
+    const profileDir = path.join(profilesDir, name);
+    const existed = fs.existsSync(path.join(profileDir, "config.toml"));
+    const profileDirExistedBefore = fs.existsSync(profileDir);
+    ensureDir(profileDir);
+    const futureProfileCfg = path.join(profileDir, "config.toml");
+
     const env = buildIsolatedEnv({
       shadow,
       realHome,
       profile: name,
+      profileCfg: futureProfileCfg,
       baseEnv: process.env,
       cloudflaredPath: findCloudflared(),
     });
-
-    const profileDir = path.join(profilesDir, name);
-    const existed = fs.existsSync(profileDir);
     let identity = null;
+    let loginSucceeded = false;
 
+    // Use throw + catch + finally so cleanup always runs. die() calls
+    // process.exit() synchronously, which would skip the finally block —
+    // and that would leave a half-created profile dir behind on failure.
+    let errorMsg = null;
     try {
       const loginResult = spawnSync("wrangler", ["login"], {
         stdio: "inherit",
         env,
       });
       if (loginResult.error) {
-        die(`Failed to run 'wrangler login': ${loginResult.error.message}`);
+        throw new Error(`Failed to run 'wrangler login': ${loginResult.error.message}`);
       }
       if (loginResult.status !== 0) {
-        die(`'wrangler login' exited with code ${loginResult.status}`);
+        throw new Error(`'wrangler login' exited with code ${loginResult.status}`);
       }
 
       const freshCfg = path.join(shadowWranglerConfig, "default.toml");
       if (!fs.existsSync(freshCfg)) {
-        die(`wrangler login completed but no config was written at ${freshCfg}`);
+        throw new Error(`wrangler login completed but no config was written at ${freshCfg}`);
       }
 
       // Verify identity via `wrangler whoami` in the same shadow.
@@ -743,18 +761,30 @@ function main() {
       const output = `${whoamiResult.stdout || ""}\n${whoamiResult.stderr || ""}`;
       identity = parseWranglerWhoamiOutput(output);
       if (!identity) {
-        die("Login succeeded but could not parse 'wrangler whoami' output");
+        throw new Error("Login succeeded but could not parse 'wrangler whoami' output");
       }
 
       // Move the fresh config into the profile directory. Use writeFile
       // (copy) so the profile config is a real file, not a symlink.
-      ensureDir(profileDir);
+      // (profileDir was already pre-created above for cache isolation.)
       const destCfg = path.join(profileDir, "config.toml");
       fs.copyFileSync(freshCfg, destCfg);
       writeMeta(profileDir, name, destCfg, identity);
+      loginSucceeded = true;
+    } catch (err) {
+      errorMsg = err.message;
     } finally {
       cleanupShadow(shadow);
+      // If login failed AND we created the profile dir as a side effect
+      // of cache isolation (it didn't exist before), clean it up so the
+      // user doesn't see a half-empty profile.
+      if (!loginSucceeded && !profileDirExistedBefore) {
+        try {
+          fs.rmSync(profileDir, { recursive: true, force: true });
+        } catch {}
+      }
     }
+    if (errorMsg) die(errorMsg);
 
     const note = existed ? " (overwritten)" : "";
     if (opts.json) {

package/lib/isolation.js

@@ -85,12 +85,15 @@ function cleanupShadow(shadow) {
 
 /**
  * Build the environment variable set that every isolated child process gets.
- * This is a pure function — no I/O.
+ *
+ * Note: not pure — when profileCfg is provided, ensures the per-profile
+ * cache directory exists so wrangler doesn't ENOENT on first write.
  */
 function buildIsolatedEnv({
   shadow,
   realHome,
   profile,
+  profileCfg = null,
   baseEnv = process.env,
   cloudflaredPath = null,
 }) {
@@ -100,9 +103,40 @@ function buildIsolatedEnv({
   env.WRANGLER_ACCOUNT = profile;
   env.WRANGLER_ACCOUNT_REAL_HOME = realHome;
   env.WRANGLER_REGISTRY_PATH = path.join(realHome, '.wrangler', 'registry');
-  env.WRANGLER_CACHE_DIR = path.join(realHome, '.wrangler', 'cache');
   env.WRANGLER_LOG_PATH = path.join(realHome, '.wrangler', 'logs');
   env.WRANGLER_SEND_METRICS = 'false';
+
+  // CRITICAL: Wrangler caches the user's selected Cloudflare account ID
+  // in `wrangler-account.json` inside `getCacheFolder()`. If multiple
+  // profiles share one cache directory, profile A's OAuth token can be
+  // paired with profile B's cached account ID, causing wrangler to
+  // write to the WRONG ACCOUNT — silently, until something like an R2
+  // bucket gets created in the wrong place.
+  //
+  // The cache must be per-profile. We point WRANGLER_CACHE_DIR at a
+  // `cache/` directory next to the profile's config.toml. Wrangler's
+  // getCacheFolder() honors this env var and skips its own cwd-based
+  // discovery (cli.js:62549).
+  //
+  // Earlier versions of this tool (≤1.2.1) pointed WRANGLER_CACHE_DIR
+  // at real $HOME/.wrangler/cache hoping to "share workerd cache" —
+  // that was wrong. workerd/cloudflared binaries live elsewhere
+  // (CLOUDFLARED_PATH / node_modules); WRANGLER_CACHE_DIR is only for
+  // config-cache files like wrangler-account.json and
+  // pages-config-cache.json.
+  if (profileCfg) {
+    const profileDir = path.dirname(profileCfg);
+    const cacheDir = path.join(profileDir, 'cache');
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+    } catch (err) {
+      process.stderr.write(
+        `[wrangler-accounts] could not create per-profile cache dir ${cacheDir}: ${err.message}\n`,
+      );
+    }
+    env.WRANGLER_CACHE_DIR = cacheDir;
+  }
+
   if (cloudflaredPath) {
     env.CLOUDFLARED_PATH = cloudflaredPath;
   }
@@ -144,6 +178,7 @@ function runIsolated({
     shadow,
     realHome,
     profile,
+    profileCfg,
     baseEnv,
     cloudflaredPath,
   });

package/lib/profile-store.js

@@ -39,20 +39,72 @@ function readExpirationTime(filePath) {
   return match ? match[1] : null;
 }
 
+function hasRefreshToken(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const text = fs.readFileSync(filePath, 'utf8');
+  // Any non-empty string value counts. Cloudflare's offline_access scope
+  // causes wrangler to store a refresh_token; profiles without that scope
+  // won't have one, and those are "really expired" once the access token
+  // runs out (~1h).
+  return /^\s*refresh_token\s*=\s*"[^"]+"/m.test(text);
+}
+
+/**
+ * Read the session state of a profile config.toml.
+ *
+ * Returns:
+ *   expirationTime:    ISO string of access_token expiry, or null
+ *   expired:           boolean — access_token past expirationTime, or null
+ *   hasRefreshToken:   boolean — whether the profile has a refresh_token
+ *                      that wrangler will auto-use for silent refresh
+ *   effective:         'valid' | 'refreshable' | 'expired' | 'unknown'
+ *     - 'valid':       access_token currently valid
+ *     - 'refreshable': access_token past expiry but refresh_token present,
+ *                      so wrangler will auto-refresh on next use (no user
+ *                      action needed)
+ *     - 'expired':     access_token past expiry AND no refresh_token,
+ *                      profile is genuinely broken, user must re-login
+ *     - 'unknown':     no expiration_time field, can't tell statically
+ */
 function readSessionState(filePath) {
   const expirationTime = readExpirationTime(filePath);
+  const refreshable = hasRefreshToken(filePath);
+
   if (!expirationTime) {
-    return { expirationTime: null, expired: null };
+    return {
+      expirationTime: null,
+      expired: null,
+      hasRefreshToken: refreshable,
+      effective: 'unknown',
+    };
   }
 
   const expiresAt = new Date(expirationTime);
   if (Number.isNaN(expiresAt.getTime())) {
-    return { expirationTime, expired: null };
+    return {
+      expirationTime,
+      expired: null,
+      hasRefreshToken: refreshable,
+      effective: 'unknown',
+    };
+  }
+
+  const expired = expiresAt.getTime() <= Date.now();
+
+  let effective;
+  if (!expired) {
+    effective = 'valid';
+  } else if (refreshable) {
+    effective = 'refreshable';
+  } else {
+    effective = 'expired';
   }
 
   return {
     expirationTime,
-    expired: expiresAt.getTime() <= Date.now(),
+    expired,
+    hasRefreshToken: refreshable,
+    effective,
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leeguoo/wrangler-accounts",
-  "version": "1.2.0",
-  "description": "AWS-style multi-account convenience for Cloudflare Wrangler — per-invocation OAuth isolation via shadow HOME.",
+  "version": "1.3.0",
+  "description": "Cloudflare Wrangler multi-account manager — save, switch, and run wrangler against multiple Cloudflare Workers accounts with AWS-style --profile and per-invocation shadow HOME isolation.",
   "license": "MIT",
   "bin": {
     "wrangler-accounts": "bin/wrangler-accounts.js"
@@ -20,7 +20,26 @@
     "accounts",
     "multi-account",
     "account-switcher",
-    "cli"
+    "account-manager",
+    "profile",
+    "profiles",
+    "oauth",
+    "login",
+    "aws-style",
+    "aws-vault",
+    "wrangler-login",
+    "wrangler-profile",
+    "wrangler-accounts",
+    "cloudflare-account",
+    "multiple-accounts",
+    "agent-skill",
+    "skill",
+    "skills-sh",
+    "claude-code",
+    "cursor",
+    "codex",
+    "cli",
+    "devtools"
   ],
   "repository": {
     "type": "git",

package/skills/wrangler-accounts/SKILL.md

@@ -77,13 +77,26 @@ Use `--json` for structured output.
 ### List and inspect profiles
 
 - `wrangler-accounts list` — text table with NAME / STATUS / EXPIRES / IDENTITY columns
-- `wrangler-accounts list --json` — structured: array of `{name, isDefault, isActive, status, expirationTime, identity}`
+- `wrangler-accounts list --json` — structured: array of `{name, isDefault, isActive, status, expirationTime, hasRefreshToken, identity, verified, verifyError}`
 - `wrangler-accounts list --plain` — one profile name per line (scriptable)
 - `wrangler-accounts list --deep` — **authoritative** check: spawns `wrangler whoami` in a shadow HOME for every profile and reports whether Cloudflare actually accepts the credentials. Slower (makes network calls), but the only way to catch revoked refresh tokens or broken profile files.
 - `wrangler-accounts status` / `status --json`
 - Pass `--include-backups` to show hidden backup profiles.
 
-**Accuracy note:** the `STATUS` column without `--deep` is derived purely from the saved `expiration_time` and tells you *when the access token will expire*, not whether the profile is actually usable. Wrangler auto-refreshes access tokens via the refresh token, so an `EXPIRED` access token is often fine in practice. When the user needs a real verdict, suggest `wrangler-accounts list --deep`.
+**STATUS values (1.3.0+):**
+
+| value | meaning | user action |
+|---|---|---|
+| `valid` | access_token is currently valid | none |
+| `valid*` / `refreshable` | access_token past expiry **BUT** refresh_token present; wrangler will auto-refresh on next use | **none** — this is fine, don't scare the user |
+| `EXPIRED` / `expired` | access_token expired **AND** no refresh_token saved; profile is genuinely broken | `wrangler-accounts login <name>` |
+| `unknown` | profile file has no `expiration_time` field | run `list --deep` to verify live |
+
+**Cloudflare OAuth lifecycle reference:** access tokens are short-lived (~1 hour) by design. Every profile with `offline_access` in its scopes also has a long-lived refresh_token (~30 days, silently extended on use). Wrangler refreshes access tokens automatically whenever it runs a command and the current one is past expiry. **Do not tell the user to re-login just because `list` shows an expired access token** — check `hasRefreshToken` first. If the profile's STATUS is `valid*` / `refreshable`, nothing is wrong.
+
+The only time a user actually needs `wrangler-accounts login <name>` again is:
+1. STATUS is `EXPIRED` (no refresh_token at all — profile was saved without `offline_access` scope)
+2. OR `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (refresh token itself got invalidated)
 
 ### Save, sync, login, remove
 
@@ -238,6 +251,56 @@ Or users can add a shell alias: `alias realhome='cd "$WRANGLER_ACCOUNT_REAL_HOME
 - "I want this account to stick for a while" → `wrangler-accounts default <name>`
 - "Just this one command" → `wrangler-accounts --profile <name> <wrangler-args>`
 
+### `[ERROR] A request to the Cloudflare API ... Authentication error [code: 10000]` with `code: 7403` ("not authorized to access this service")
+
+The OAuth token is fine but **the URL contains the wrong account ID**. wrangler caches the user's selected account in `wrangler-account.json`. If that cache file is shared across profiles, profile A's OAuth token gets paired with profile B's cached account ID, sending API calls to the wrong account. Symptoms:
+
+- `deploy` and `secret put` succeed (they don't put account ID in the URL path)
+- `d1 execute --remote`, `r2 object get/put`, anything else with `/accounts/<id>/...` in the URL fails with 7403
+
+**Fix path** (in order):
+
+1. **Are you on wrangler-accounts ≥ 1.2.2?** Run `wrangler-accounts --version`. If `< 1.2.2`, upgrade — earlier versions pointed `WRANGLER_CACHE_DIR` at a shared global path. 1.2.2 isolates the cache per profile.
+2. **Clear the polluted shared cache** (one-time, even after upgrading):
+   ```bash
+   rm -f ~/.wrangler/cache/wrangler-account.json
+   rm -f ~/Library/Preferences/.wrangler/cache/wrangler-account.json   # macOS env-paths fallback
+   ```
+3. **Verify with `wrangler-accounts list --deep`** — the VERIFIED column for each profile should be `✓ ok`. If `✗`, the underlying OAuth session itself is broken; run `wrangler-accounts login <name>`.
+4. **Defense in depth**: set `CLOUDFLARE_ACCOUNT_ID=<correct-id>` in the calling environment. wrangler reads this env var directly and bypasses the cache entirely. Useful for scripts or one-off recovery commands:
+   ```bash
+   CLOUDFLARE_ACCOUNT_ID=<id> wrangler-accounts <profile> r2 object put ...
+   ```
+
+**What to tell the user**: "wrangler returned 7403 because it cached the wrong account ID alongside your OAuth token. This was a real bug in wrangler-accounts ≤ 1.2.1 (shared cache directory across profiles). Upgrade to 1.2.2 and clear the polluted cache."
+
+### "The OAuth config seems right, but the wrong account is being used"
+
+Same root cause as the 7403 above. Default to the same fix path.
+
+### `wrangler dev` (or any `--local` command) shows stale data after switching profiles
+
+Project-local state at `<project>/.wrangler/state/` is **NOT** isolated per profile — wrangler's `getLocalPersistencePath` (cli.js:149025) hardcodes the path next to `wrangler.toml` and the only override is the `--persist-to` CLI flag (no env var hook). So if profile A's `wrangler dev` populated a local D1 emulation, then you switch to profile B and run `wrangler dev` in the same directory, B sees A's emulated rows.
+
+This only affects `--local` simulations. **`--remote` commands hit Cloudflare directly and are unaffected** — that's the common case for d1/r2 work in a multi-account setup.
+
+Two clean fixes:
+
+1. **Use git worktrees** (recommended for any serious multi-profile dev workflow):
+   ```bash
+   git worktree add ../my-project-work main
+   git worktree add ../my-project-personal main
+   cd ../my-project-work && wrangler-accounts exec work     # isolated .wrangler/state/
+   cd ../my-project-personal && wrangler-accounts exec personal
+   ```
+2. **Clear state manually before switching**:
+   ```bash
+   rm -rf .wrangler/state
+   wrangler-accounts --profile <new> dev
+   ```
+
+`wrangler-accounts` does not auto-isolate `.wrangler/state/` because the only mechanism would be argv injection of `--persist-to`, which has too many failure modes (different subcommands accept persistTo at different positions, can't override user-supplied flags, path selection is ambiguous between per-profile and per-profile-per-project). The honest tradeoff is documented in the "What is and isn't isolated" table above — partial isolation with hidden gotchas would be worse than honest sharing.
+
 ### Shell history / `.zsh_history` seems to grow when running `exec`
 
 Intentional. By design the shadow HOME symlinks all top-level entries of real HOME except `.wrangler`, so shell history writes pass through to the real file. This is a **convenience** bias, not a clean-room sandbox — the goal is that `exec` subshells feel like a normal terminal with a different Cloudflare account, not a jail.
@@ -245,10 +308,25 @@ Intentional. By design the shadow HOME symlinks all top-level entries of real HO
 ## Invariants the AI should rely on
 
 - **Real `~/.wrangler/config/default.toml` is never written to by `wrangler-accounts`.** If a user reports that it changed, something else touched it (e.g. a direct `wrangler login` outside `wrangler-accounts`).
-- **Two `wrangler-accounts --profile A` and `wrangler-accounts --profile B` running in parallel never clobber each other.** Each gets its own `mkdtemp` shadow HOME.
+- **Two `wrangler-accounts --profile A` and `wrangler-accounts --profile B` running in parallel never clobber each other on credentials OR account-id cache.** Each gets its own `mkdtemp` shadow HOME, and each gets its own per-profile `WRANGLER_CACHE_DIR` (next to the profile's `config.toml`) so that wrangler's `wrangler-account.json` (which stores the selected Cloudflare account ID) is naturally isolated.
 - **OAuth token refresh inside a profile is automatic.** The shadow HOME contains a symlink from `.wrangler/config/default.toml` to the saved profile file, so Wrangler's in-place `fs.writeFileSync` during `refreshToken()` flows straight back to the profile.
 - **`wrangler-accounts <args>` without a management subcommand forwards everything to wrangler verbatim**, including `--env`, `--dry-run`, `--json`, and any wrangler-native flags. The only flags consumed by `wrangler-accounts` itself are the ones listed in "Paths and environment" below.
 
+## What is and isn't isolated
+
+| State | Location | Isolated? |
+|---|---|---|
+| OAuth credentials (`config.toml`) | shadow `$HOME/.wrangler/config/default.toml` → symlink to per-profile file | ✅ per profile |
+| Account-id cache (`wrangler-account.json`) | per-profile `WRANGLER_CACHE_DIR` (= `<profilesDir>/<name>/cache/`) | ✅ per profile |
+| Pages config cache (`pages-config-cache.json`) | same as above | ✅ per profile |
+| Miniflare dev registry | `WRANGLER_REGISTRY_PATH` = `$realHome/.wrangler/registry` | ❌ shared on purpose (cross-profile worker discovery during local dev) |
+| Wrangler debug logs | `WRANGLER_LOG_PATH` = `$realHome/.wrangler/logs` | ❌ shared (append-only, harmless) |
+| Project-local state (`./.wrangler/state/`, `./node_modules/.cache/wrangler`) | inside the project directory | ❌ shared at project level (per-project, but not per-profile) |
+| `cloudflared` binary | `CLOUDFLARED_PATH` or `~/.wrangler/cloudflared/` | ❌ shared (binary, not account-scoped) |
+| Shell history, npm cache, git config, ssh keys | symlinked through to real `$HOME` | ❌ shared by design (so `exec` subshells feel like a normal terminal) |
+
+If a user is hitting a "wrong account" symptom and the credentials look right, the most likely culprit is **project-local state** in `./.wrangler/state/` — clear that and re-run.
+
 ## CI guidance
 
 For CI and deploy pipelines, **use `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` with plain `wrangler`**, not saved OAuth profiles. `wrangler-accounts` is a local developer convenience for juggling OAuth sessions on your workstation, not a CI primitive.