claude-multiacc 2.0.57 → 2.0.59

package/bin/codex-accounts

@@ -2,7 +2,7 @@
 # codex-accounts — manage the codex-multiacc account pool (OpenAI Codex CLI).
 # Subcommands: list status add import adopt dedupe remove login expired relogin
 #              sync verify limits post-sync health self-update
-#              export-credential import-credential
+#              export-credential import-credential model-catalog
 set -u
 # lib/codex_audit.py is imported by several subcommands; keep the install tree free
 # of __pycache__ (it may be root-owned, read-only, or an npm global prefix).
@@ -98,7 +98,14 @@ USAGE
       stay selectable. Skips accounts fetched in the last 45s and honors
       429/refresh backoff; --force ignores all three.
   codex-accounts health                     limits + full verify; logs to health.log
-  codex-accounts self-update                update this npm/git install; logs to update.log
+  codex-accounts self-update                update this npm/git install (never to an older version); logs to update.log
+  codex-accounts model-catalog [refresh|show] [--if-stale] [--quiet]
+      the model/effort catalog auto-resume relaunches a session with. refresh (the default)
+      merges the catalog this release ships with the model caches the CLIs keep in their
+      account dirs (no request, no credential) into model-catalog.json in BOTH pool roots;
+      every install and self-update runs it, and each limits pass refreshes its own pool's
+      copy once it is an hour old. --if-stale leaves a younger copy alone; --quiet prints
+      nothing. show prints the merged catalog.
   codex-accounts post-sync                  (server side) seed dirs, fix perms, quick verify
   codex-accounts mcp add <name> [--provider claude|codex|both] [--scope user]
                           [-e KEY=VAL]... [-H 'Header: v']... [--transport stdio|http]
@@ -139,6 +146,8 @@ ENV
   CODEX_MULTIACC_DISABLE=1  bypass the shim entirely
   CODEX_MULTIACC_AUTO_RESET=0  disable automatic usage-reset redemption
   CODEX_MULTIACC_MCP=0   disable the MCP registry (no reconcile at seed/launch, no mirror)
+  CODEX_MULTIACC_MODEL_CATALOG=0  never refresh the codex pool's model-catalog.json
+                        (MULTIACC_MODEL_CATALOG=0: neither pool's)
 EOF
 }
 
@@ -1837,6 +1846,8 @@ PYEOF
   # lock while a consumer reads its output.
   codex_limits_lock_release
   trap - EXIT
+  # This pool's model catalog, once its copy is an hour old (lib/common.sh).
+  model_catalog_backstop
   # The refresher fails open per account; a NON-zero status means the pass itself
   # broke (unreadable manifest, dead python). Report the state anyway — stale data
   # beats silence — but hand the caller the failure, exactly as before --json existed.
@@ -2251,6 +2262,10 @@ cmd_mcp() {
   local args=()
   case "$sub" in
     add|add-json|remove|list|apply|import-local) shift ;;
+    # Sharing MCP OAuth logins across accounts is a claude-pool feature (lib/mcp_oauth.py):
+    # Codex keeps an MCP server's OAuth state in its own per-account store.
+    auth-status|auth-sync|auth-forget)
+      die "mcp $sub is not supported for the codex pool — MCP OAuth logins are shared across the claude pool only (claude-accounts mcp $sub)" ;;
     "") usage; return 1 ;;
     *) die "unknown mcp subcommand: $sub (add, add-json, remove, list, apply, import-local)" ;;
   esac
@@ -2369,7 +2384,17 @@ cmd_self_update() {
         ulog "self-update: already latest ($cur)"
         return 0
       fi
-      ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix, npm $npm_bin)"
+      # Only ever UP, to a version known to be newer (claude-accounts says why): the same
+      # package, so either CLI could otherwise install `latest` over a newer hand install.
+      case "$lat" in [0-9]*.*[0-9]) ;; *)
+        ulog "self-update: could not read the registry's version (npm view); not updating"
+        return 1 ;;
+      esac
+      if ver_newer "$cur" "$lat"; then
+        ulog "self-update: this install ($cur) is newer than the registry's $lat; not downgrading"
+        return 0
+      fi
+      ulog "self-update: npm $cur -> $lat (prefix $prefix, npm $npm_bin)"
       if PATH="$npm_path" "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
            >>"$ACC_ROOT/update.log" 2>&1; then
         after="$(pkg_version_at "$REPO_DIR")"
@@ -2378,6 +2403,7 @@ cmd_self_update() {
           return 1
         fi
         ulog "self-update: npm update ok ($after)"
+        model_catalog_after_update "$quiet"
       else
         ulog "self-update: npm update FAILED (see update.log)"
         return 1
@@ -2441,7 +2467,7 @@ PYEOF
 # distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
 # FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
 # the dispatcher below implements, and a test pins that both ways.
-_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool mcp"
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool mcp model-catalog"
 case " $_KNOWN_VERBS " in
   *" ${1:-help} "*)
     # ...but never past a literal `--`: from there on the words belong to an MCP
@@ -2473,6 +2499,7 @@ case "${1:-help}" in
   self-update) shift; cmd_self_update "$@" ;;
   init-pool) shift; cmd_init_pool "$@" ;;
   mcp) shift; cmd_mcp "$@" ;;
+  model-catalog) shift; cmd_model_catalog "$@" ;;
   help|--help|-h) usage ;;
   *) usage; exit 1 ;;
 esac

package/docs/ACCOUNT_OPERATIONS.md

@@ -59,7 +59,9 @@ claude-accounts adopt acct-01
 `adopt` makes the account dir a **symlink to `~/.claude`** — the machine's existing
 login joins the pool with a single credential file (no copy of the OAuth grant exists
 anywhere else, so refreshes can never race). This is how the two current accounts run:
-acct-01 = the Mac's login, acct-02 = the server's login (adopted server-side).
+acct-01 = the Mac's login, acct-02 = the server's login (adopted server-side). It refuses
+an account dir that already holds a credential of its own — any `.credentials.json`, even
+one with only MCP server sign-ins in it, or a `server.token` — rather than delete it.
 
 ### Add a fresh account (~1 min, one browser sign-in)
 
@@ -212,6 +214,62 @@ is applied on the Mac and never synced. `--help` on `mcp` lists every option;
 `CLAUDE_MULTIACC_MCP=0` / `CODEX_MULTIACC_MCP=0` stop the reconcile at seed and launch and the
 shim's mirror (the CLI, sync and fan-out keep working).
 
+### MCP OAuth logins (per machine, shared by every account)
+
+The registry carries a server's CONFIG; an OAuth server's LOGIN lives in each account's
+credential store (`mcpOAuth` in `.credentials.json`, or the account's Keychain item). The
+claude pool shares those logins across every account on the machine through
+`<pool>/mcp-oauth.json` (lib/mcp_oauth.py): authenticate a server once in any account
+(`/mcp` in a session) and every account has it from its next launch. It goes into the store
+each account already has — its `.credentials.json`, or its Keychain item — and an account that
+runs on its setup token with no file gets one created, holding the MCP logins alone (0600):
+in an ssh/tmux session that file is all its client reads them from, and it is no Claude login
+to the shim, the limits pass, the audit or verify (`list` keeps showing `auth=token`). No file
+is created beside a Keychain login, in a parked account (`.expired`) or an adopted dir.
+
+```bash
+claude-accounts mcp auth-status                # server, expiry, source account, refresh state, per-account stores
+claude-accounts mcp auth-sync                  # what the limits pass does every 15 minutes, now
+claude-accounts mcp auth-sync --force          # ...retrying a refresh that is backing off
+claude-accounts mcp auth-forget higgsfield     # deliberate logout, every account on this machine
+```
+
+What to expect, and how to read `auth-status`:
+
+- **fresh / stale / own / stub / missing / absent** per account file or Keychain item. `stale`
+  (a provably older copy), `stub` and `missing` turn `fresh` at that account's next launch (the
+  shim merges before exec) or at the next limits pass; `own` is a login of another grant whose
+  age the expiries cannot settle — left where it is; `locked` means the item exists but this
+  session (ssh, tmux) cannot open it — a Terminal on the Mac, or the scheduled pass, reaches it.
+  An `absent` file turns `fresh` only for a setup-token account (the file is created for it);
+  an absent Keychain item is never created.
+- **NOT shared: …** / **sharing paused: …**: one login in many accounts needs ONE refresher —
+  the pool, ahead of every client — so nothing is shared with
+  `CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0`, by a launch when no refreshing limits pass ran in the
+  last hour (`mcp auth-sync` runs one now), or for a login inside the clients' own 5-minute
+  window, refused by its server, or whose failing refresh would next try too late. Each
+  account keeps what it holds meanwhile.
+- **NEEDS RE-AUTH**: the authorization server refused the refresh token. Sign in again in any
+  one account (`/mcp`); the new login replaces the old one everywhere. A backoff (`N
+  failure(s), last http 503`) retries by itself, 15 minutes doubling to 6 hours; `refresh: due
+  … — deferred: a copy sits in acct-NN keychain` waits for a pass that can open that item,
+  until 20 minutes before expiry.
+- **Never synced**: each Mac keeps its own grants. A runner Mac, a replica and the source
+  each sign in once; `sync` and the limits fan-out push explicit file lists without it.
+- **Logging out**: a `/mcp` "Clear authentication", `claude mcp login <server>` or a
+  re-authentication in ANY one account revokes the shared login at the server, so the pool
+  retires it in every account (`login: none — retired … (cleared in acct-NN file)`); one
+  sign-in in any account shares the new one. `mcp auth-forget NAME` is the same logout from
+  the operator's side. `codex-accounts mcp auth-*` is not supported (Codex keeps MCP OAuth in
+  its own store).
+- **Rolling it out**: the first share runs at install time (the limits agent starts on
+  install), and a build older than this one reads a shared MCP-only file as a live login:
+  every setup-token account would then say "Not logged in". Install it only where no older
+  build can come back: from the registry once it is published, or by hand at or above the
+  registry's version (npm `self-update` never installs an older one). Until then, hold the
+  sharing with `CLAUDE_MULTIACC_MCP_OAUTH=0` (`launchctl setenv` before the install for the
+  scheduled agents).
+
 ### Pointing sync somewhere else (or nowhere)
 
 The target is no longer baked in. In precedence order:
@@ -332,7 +390,7 @@ emitted for diagnostics.
 | Credential | Where it lives | Class | Can it be copied to another machine? |
 | --- | --- | --- | --- |
 | claude setup-token | `<acct>/server.token` | **portable** | **Yes**; the fleet-distributed credential |
-| claude OAuth login | `<acct>/.credentials.json`, or a macOS Keychain item | machine-local | **No**; refresh tokens rotate |
+| claude OAuth login | `<acct>/.credentials.json`, or a macOS Keychain item, carrying `claudeAiOauth` (MCP OAuth state alone is no login) | machine-local | **No**; refresh tokens rotate |
 | codex ChatGPT login | `<acct>/auth.json` | machine-local | **No**; Codex has no portable credential |
 
 Non-portable accounts are not a dead end: they show up as `credential_class:
@@ -422,6 +480,8 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 | `CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY=<s>` | five-hour recovery grace; default 300s (weekly never clears early) |
 | `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
 | `CLAUDE_MULTIACC_AUTORESUME=0` | no [auto-resume](AUTORESUME.md) watcher for launches from this environment. `touch <pool>/autoresume.off` also stops running watchers |
+| `CLAUDE_MULTIACC_MCP_OAUTH=0` | stop sharing MCP OAuth logins across accounts (no merge before exec, no sync in the limits pass); `auth-status` / `auth-forget` still run |
+| `CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0` | never refresh MCP OAuth logins — and so share none: a login in many accounts needs ONE refresher, or their clients refresh one rotating grant at once (each account keeps what it holds) |
 | `CLAUDE_ACCOUNTS_ROOT=...` | relocate the pool; legacy spelling is `CLAUDE_ACCOUNTS_DIR` |
 | `CLAUDE_MULTIACC_SYNC_TARGET=...` | sync target, overriding the manifest; `none` = local-only |
 | `CLAUDE_MULTIACC_SYNC_ROOT=... / _SYNC_REPO=...` | remote pool root / addon repo that goes with it |

package/docs/AUTORESUME-HANDOFF.md

@@ -28,6 +28,8 @@ available; a Codex ID is never passed as a Claude native `--resume` ID, or vice
 The watcher uses the history already bound to the source client. It does not guess from
 the newest transcript or directory name. Invalid, ambiguous or unavailable source
 history prevents the handoff before the source client is stopped.
+Codex main conversations marked `source=cli` or `source=vscode` are supported when
+resumed in a supervised TUI; their exact conversation and file identity still must match.
 
 If another live client holds the same source conversation, the watcher holds to avoid
 creating duplicate destination conversations. Stale process records do not count.
@@ -40,9 +42,34 @@ Account avoidance is separate for each provider, so Claude's `acct-01` and Codex
 
 ## Permissions and arguments
 
-The working directory is preserved. Source model names, effort settings, session
-selectors and the original launch prompt are not replayed as destination CLI arguments.
-The destination uses its own configured model.
+The working directory is preserved. Session selectors, the original launch prompt and the
+source's own model and effort flags are not replayed as destination CLI arguments. The
+destination starts on the model and effort of the **same level** instead. Both are read from
+the validated source history, up to its snapshot boundary, and matched through the
+[model catalog](../README.md#auto-resume):
+
+- **Models match by level** (operator's map, 2026-10-14):
+
+  | Codex source | Claude destination | | Claude source | Codex destination |
+  |---|---|---|---|---|
+  | astra | opus | | fable, mythos | astra |
+  | sol | sonnet | | opus | astra |
+  | terra | haiku | | sonnet | sol |
+  | luna | haiku | | haiku | terra |
+
+  The catalog encodes it as levels: Claude haiku 2, sonnet 3, opus 4, fable 5 (mythos counts
+  as fable); Codex luna 1, terra 2, sol 3, astra 4. Equal levels match; a level with no
+  family on the other side (luna, fable) takes the nearest one, the higher on a tie. The
+  match is that family's newest listed model, whatever its version (launches are staggered,
+  so a family a release behind is still its own level). A retiring model counts as the model
+  the catalog upgrades it to.
+- **Efforts match by name.** low, medium, high, xhigh and max carry over unchanged. Codex's
+  `ultra` becomes `max`, and `minimal` or `none` becomes `low`. The result is clamped to the
+  destination model: the nearest supported level below, else its lowest.
+- **Unknown means the destination's default.** A model or effort the history does not
+  record, or the catalog cannot place, is left out, and the destination CLI applies its own
+  default. Claude takes either flag alone. Codex takes both or neither, with the matched
+  model's default effort when only the model is known.
 
 An explicit permission bypass maps to the equivalent destination bypass. Merely allowing
 a bypass flag is not treated as enabling it. Ordinary launches use explicit conservative

package/docs/AUTORESUME.md

@@ -1,7 +1,8 @@
 # Auto-resume (interactive sessions in tmux)
 
 An interactive `claude` or `codex` session that stops on a usage limit, a failed login, an
-API error or (claude only) a crash is restarted automatically on another pooled account
+API error or (claude only) a crash or [critical memory usage](#claude-critical-memory) is
+restarted automatically on another pooled account
 with headroom. Within the same provider it keeps the **same session id, directory and
 flags**, and you press no keys. When a quota recovery has no usable account left in that
 provider, it can continue in the other provider using the source conversation's history.
@@ -69,7 +70,12 @@ shell:   runs the shim again → token → marker on the old account → normal
 2. **The watcher reads what the client already writes.**
    - **Claude:** `<acct>/sessions/<pid>.json` names the session. The watcher re-reads it
      every tick, so it follows `/clear` and `/resume` inside the TUI. The transcript
-     under `projects/` records every API error.
+     under `projects/` records every API error of the main thread. Subagents and workflow
+     agents keep their own transcripts beside it; the watcher follows those too, but only
+     for the account's own verdicts (see
+     [subagent transcripts](#claude-subagent-and-workflow-transcripts)). The client's
+     critical-memory warning reaches no transcript, so for that one the watcher reads its
+     own pane (see [critical memory](#claude-critical-memory)).
    - **Codex:** the rollout under `sessions/` is found in one of three ways, in order:
      - the `resume` id;
      - the native process's open files;
@@ -81,16 +87,23 @@ shell:   runs the shim again → token → marker on the old account → normal
      transcript never fires. An automatic Codex restart also carries the previous
      rollout's inode and byte offset: the new watcher starts after those bytes, so a
      quota event from the same second cannot trigger another rotation.
-   - Subagent (sidechain) records are ignored.
+   - Subagent (sidechain) records in the main transcript are ignored.
 3. **It waits for the error to settle.**
    - **Grace period:** a verdict has to stand for 5 s.
    - **Cancellation:** a message you type cancels it. So does the client's own
-     auto-continue producing a normal reply. For codex, a new user message,
-     `task_started` or `turn_aborted` cancels it.
+     auto-continue producing a normal reply. A slash command that only shows or
+     configures the session (`/model`, `/effort`, `/usage`, `/status`, `/mcp` …) cancels
+     only a model-limit or transient verdict: `/model` is how you handle one model's
+     limit, but a usage-limited, logged-out or refused account is just as stuck after it.
+     Any other command counts as typing: `/login` and `/limit-reset` are how you fix the
+     account itself. A verdict a subagent recorded is also cancelled by a newer reply in
+     any subagent transcript. For codex, a new user message, `task_started` or
+     `turn_aborted` cancels it.
    - **Transient errors** wait longer: 30 s, then 60 s, then 120 s on repeats.
    - **Model-limit and transient errors** also wait until no subagent transcript has
      changed for 20 s, for up to 15 min. That background work may be healthy, or running
-     on another model.
+     on another model. An agent meeting the account's own limit meanwhile ends the wait:
+     its verdict outranks the main thread's (see [subagents](#claude-subagent-and-workflow-transcripts)).
 4. **It asks before it acts.** The watcher runs the shim in *probe mode*
    (`CLAUDE_MULTIACC_AR_PROBE=1`). This is the same candidate loop and the same argv the
    relaunch will use. It prints `pick=acct-NN tier=…` and never execs.
@@ -159,6 +172,16 @@ shell:   runs the shim again → token → marker on the old account → normal
       (`projects[<dir>].hasTrustDialogAccepted`). Claude asks "Is this a project you
       trust?" in a directory an account has never opened, even with
       `--dangerously-skip-permissions`, and nobody is there to answer.
+      **codex:** it saves `projects[<dir>].trust_level = "trusted"` in the selected
+      account's `config.toml` before startup, so the **Folder access / Trust this
+      folder?** screen cannot block the continuation. This also covers a handoff from
+      Claude. Only a consumed automatic relaunch token enables this step; normal
+      launches keep their existing trust decisions. The logical, physical and on-disk
+      spellings of the directory are covered (Codex looks the canonical one up first), an
+      explicit `untrusted` answer is overridden (nobody is there to answer again), and
+      unrelated settings and file permissions are preserved. An unreadable, invalid or
+      concurrently changed config is left untouched and logs `autoresume trust-failed`;
+      Codex then asks on its own screen and the watcher gives up on the missing prompt.
    6. The new pick gets a watcher of its own.
    7. For Codex, the old watcher waits up to 30 seconds for the exact continuation
       prompt to appear as a new user message in the same rollout. Only then does it log
@@ -180,7 +203,8 @@ The relaunch starts from the original argv:
   `resume <id>|--last`) and the original prompt are removed.
 - `--resume <sid> "<prompt>"` is appended. For codex the command becomes
   `resume <options> <sid> "<prompt>"`.
-- An explicit `--model` from the original launch is kept. No model is added otherwise.
+- The session's own model and effort are carried over, as described below, in place of
+  launch options that a `/model` or `/effort` switch made stale.
 - Codex's explicit or automatically selected `--no-daemon` is kept.
 
 The prompt is submitted automatically:
@@ -191,11 +215,45 @@ The prompt is submitted automatically:
 > may still be running. Inspect its state before relying on it or restarting it, and do
 > not duplicate active or completed work.
 
-- **The reason** follows the class.
-- **Transient and crash restarts** drop "on another account".
+- **The reason** follows the class; a memory restart's names the size the banner showed.
+- **Transient, crash and memory restarts** drop "on another account".
 - **To replace the whole text**, set `CLAUDE_MULTIACC_AUTORESUME_PROMPT` or
   `CODEX_MULTIACC_AUTORESUME_PROMPT`.
 
+### Model and effort
+
+The watcher reads the model and effort from the session's own history when it decides to
+relaunch, so a `/model` or `/effort` switch made after the launch is honoured:
+
+- **Claude:** the last main-thread assistant record, never a subagent's or a meta record.
+  The model is its `requestedModel`, else `message.model`. The effort is its `effort`, else
+  `perTurnEffort`. A `/model` switch with no reply after it is not visible yet, because only
+  assistant records carry the model.
+- **Codex:** whichever comes last of a `turn_context` (`model`, `effort`) and a
+  `thread_settings_applied` event for the rollout's own thread (`model`,
+  `reasoning_effort`). This is the rule Codex's own state database follows.
+
+They become flags placed before the session id:
+
+- **Claude** gets `--effort E`, because `--resume` never restores the effort. It gets no
+  model flag: `--resume` restores the session's model itself, and an explicit `--model`
+  would turn that restore off and put the shim in explicit-model mode, where its
+  model-scoped fallback (the Fable bucket) no longer applies. A launch `--model` is replayed
+  as given until the history shows the session ran on another model; then it is dropped and
+  `--resume` takes over. The relaunch file names that model (`model=`), so the shim pins its
+  fallback model only for a session that is on the limited model itself: an Opus session
+  relaunched onto an account whose Fable bucket is full resumes on Opus, not the fallback.
+- **Codex** gets `-m M -c model_reasoning_effort=E`, always both or neither: a model or an
+  effort flag alone makes Codex drop the thread's other saved value. An effort the history
+  does not name becomes that model's default from the catalog; with no default either, the
+  launch's own model and effort options are dropped too, and Codex restores both from the
+  thread.
+
+The [model catalog](../README.md#auto-resume) also clamps an effort to the levels that
+model supports. A value the history does not record is left out, and a history that cannot
+be read relaunches with the launch's own options, as before. The `switch` line records
+what the relaunched client was given (`model=`, `effort=`).
+
 ## What counts as what
 
 **Claude**, from the transcript's API-error records:
@@ -207,10 +265,18 @@ The prompt is submitted automatically:
 | auth | `authentication_failed` | `.expired`, the shim's client-reported auth park | 1 h |
 | blocked | `oauth_org_not_allowed` | persistent `.expired` `org-blocked` park | 6 h in this chain |
 | blocked | `account_on_hold`, `billing_error`, `verification_required` | nothing: only this chain avoids it | 6 h |
-| transient | `overloaded`, `server_error`, `unknown`, any other `rate_limit` | nothing | none, so the same account may continue |
+| transient | `overloaded`, `server_error`, `unknown`, `rateLimitType` `concurrents` (too many requests in flight at once; the account serves the next one), any other `rate_limit` | nothing | none, so the same account may continue |
 | crash | the process ended on its own after ≥ 60 s, leaving its session registry behind | nothing | none, so normal selection applies |
+| memory | not a record: the client's `Critical memory usage (<size>)` banner in its own pane ([critical memory](#claude-critical-memory)) | nothing | none, so normal selection applies |
 | never | anything else (`invalid_request`, `max_output_tokens`, `model_not_found`, …) | nothing | not restarted; logged once |
 
+An auth verdict parks the credential the stopped run carried: the launching shim writes
+`via=token|login` into the watcher's state, and the relaunch file carries it (`via=`), so
+a portable token that failed is retired as `setup-token-invalid` (its proof dropped) and a
+login gets `auth-error`, even in a session the client switched the run to with `/clear`
+or `/resume`, which no session-index line names. A relaunch file without `via=` (an older
+watcher) falls back to the session's index line.
+
 An organization refusal carries `rtype=oauth_org_not_allowed` into the relaunch file,
 so the shim parks the old account even if its earlier session-index capture missed it.
 An admin must enable access, then full `claude-accounts verify` must prove it; a PASS
@@ -247,9 +313,188 @@ Codex differs from claude in two ways:
 - at most 20 relaunches;
 - 8 rotations per hour;
 - 3 transient restarts per hour;
-- 2 crash restarts per 10 minutes.
+- 2 crash restarts per 10 minutes;
+- 2 memory restarts per hour.
+
+Over budget, the watcher leaves the session alone. Over the memory budget it gives up on
+that process's memory for good (logged once) and goes on watching for everything else.
+
+### Claude subagent and workflow transcripts
+
+An account limit can reach only the background agents. On 2026-10-19 two sessions sat
+idle behind paused workflows: the workflow agents had recorded the five-hour limit, the
+client knew it and sent no further main-thread request, and the main transcript showed
+nothing to act on. So the watcher also follows the session's
+`<sid>/subagents/agent-*.jsonl` (Agent tool subagents) and
+`<sid>/subagents/workflows/wf_*/agent-*.jsonl` (workflow agents) beside the transcript.
+
+- **Only the account's own verdicts count there:** quota (`five_hour` / `seven_day`
+  rejected), auth (`authentication_failed`) and blocked (the codes in the table above).
+  A subagent's model-scoped limit, transient error or any other error is its own and is
+  ignored, and so are its user records: they are its parent's prompts, never a human.
+- **From this launch only:** a record needs a timestamp from this launch, and a
+  rejection one from at least a second after it. The main thread's two seconds of slack
+  before the launch would admit the last rejections of the process a relaunch replaced:
+  its workflow agents meet a limit in bursts that span seconds and run on until it is
+  stopped, a second or two before the relaunch. A transcript last written before the
+  launch is followed from its end.
+- **The main thread comes first, unless the account is out.** A main-thread quota, auth
+  or blocked verdict stands over any subagent's. Several agents meeting the same limit make
+  one verdict. An account verdict, though, outranks a model-limit or transient one,
+  whichever thread met it first: the account serves the main thread no better, and the
+  model/transient verdict would wait on agents that are only being refused. On 2026-10-20 a
+  session sat six minutes behind its main thread's `concurrents` rejection while all its
+  agents met the five-hour limit. The outranked verdict waits behind it and stands
+  again only if that one goes without the main thread having moved on: an agent's newer
+  reply answers the account, or a quota reset passes. Anything the main thread does next
+  (typing, `/model`, a reply, another rejection) ends it.
+- **The latest reset is the one marked.** Rejections of one class — main thread and
+  agents alike — are one verdict, marked with the latest reset any of them named and that
+  reset's type: a five-hour limit in one transcript and the weekly one in another keep the
+  account out until the weekly one lifts.
+- **A limit that has reset is no verdict.** A quota rejection whose `resetsAt` has passed
+  is dropped when it is read, and a pending one whose reset passes while it waits (the
+  grace, a hold for want of room) is dropped then, never acted on; a rejection without a
+  `resetsAt` stands as before. This holds for the main thread too.
+- **Cancellation:** a real reply to a request sent after the verdict, in the main thread
+  or in any subagent transcript, or a message you type. A reply counts from when its
+  request was sent: the `api-request` record the client writes right before each request,
+  which the reply names by `requestRef` (the reply's own timestamp when there is none). A
+  stream the account accepted before the limit can end many minutes after it, and an
+  agent's final answer streamed that way, the last record a paused workflow writes, must
+  not stand for the account serving again. A slash command that only shows or configures
+  the session never counts, any other one (`/login`, `/limit-reset` …) does, and a
+  `<synthetic>` record (the client's own words, not the API's) never does. Records older
+  than the verdict cancel nothing, whatever order the transcripts are read in.
+- **A restarted watcher replays safely.** A watcher started onto a session launched hours
+  ago reads everything written since that launch. While nothing is pending it skips the
+  main thread's lines unparsed (its request records excepted), but the latest real reply
+  or typed message among them still counts: an agent's rejection older than it never
+  becomes a verdict. An old workflow limit cannot stop a session whose main thread has
+  been served since. Nor can one whose agents have been: a subagent's verdict is acted on
+  only once every followed transcript is read to its end, which can take a minute of
+  ticks for a session with hundreds of megabytes of agent transcripts.
+- **It waits for the main thread's work in flight.** A main-thread verdict comes from the
+  main thread's own rejected request, so whatever it was doing has ended by then; an
+  agent's verdict can come mid-tool or mid-stream. So it is not acted on while the
+  main thread's newest request (`querySource` `repl_main_thread`) has nothing back yet,
+  while that request's reply is still streaming (its newest block has `"stop_reason":
+  null`, or says `tool_use` before the tool_use block is written), or while a tool the
+  reply started has no `tool_result` yet. Stopping the client would kill the tool's
+  processes with it. This is keyed by request, never by the file's order: the client
+  writes the request record as it sends, sometimes before the prompt that led to it and
+  before the previous reply's last blocks. An API error after the request, the client's
+  `[Request interrupted by user` record, or a finished reply ends the wait. So does a
+  main-thread rejection of its own, which then stands in the agent's verdict's place. The
+  wait is capped at `CLAUDE_MULTIACC_AR_SUBAGENT_CAP` (15 min) from when the verdict
+  became pending; a tool waiting for a permission nobody gives waits that long. The
+  watcher keeps the main transcript's newest 4 MB of lines for this and reads the file no
+  second time; the wait is logged once, as `hold reason=main-<request|stream|tool>`. An
+  idle main thread (a finished reply, queued task notices, `/model`) moves at the grace as
+  before. The agents' own streams and tools are not waited for: the paused workflow ends
+  with the session either way.
+- **Everything after that is the main thread's path:** grace, budgets, probe, hold,
+  cross-provider continuation, the old account's marker and the `switch` line. The
+  `detect` line adds `src=sidechain agent=<agentId>`.
+- **Bounds:** new transcripts are looked for every 5 s
+  (`CLAUDE_MULTIACC_AR_SUBAGENT_SCAN`), in a walk of at most 5000 entries. The 128 most
+  recently written are followed and share 16 MB of reading per tick; they are read only
+  once the main transcript is caught up. Only their API-error and request lines and each
+  read's latest reply are parsed, the reply found from the read's end. A workflow's
+  `journal.jsonl` and an agent's `*.meta.json` are not transcripts.
+
+### Claude critical memory
+
+Claude Code checks its own heap every 10 s (2.1.304: `process.memoryUsage().heapUsed`). From
+2.5 GiB on it shows, in red, in the notification column at the right of the prompt's footer:
+
+```
+  ⏵⏵ bypass permissions on · 3 shells      Critical memory usage (8.3GB) — restart and resume with claude --continue, or run /compact
+```
 
-Over budget, the watcher leaves the session alone.
+It writes nothing of this to the transcript. On 2026-10-20 a session running eight
+background workflows reached 8.3GB. The fix is what the banner says, so the operator's rule
+is the usage-limit one: the session is restarted and resumed automatically.
+
+- **Where it is read:** the watcher reads its own pane, read-only, with `tmux capture-pane
+  -p -J` on the socket and pane from its state file. It never sends a key. It reads only
+  while the pane is still the launching shell's and the client runs in the foreground of its
+  terminal (not suspended), and only for a session it can name to `--resume`.
+- **What counts:** only the footer of the prompt's box. The box is found by its shape:
+  a rule across the pane from its first column, right under it the prompt's row (the mode
+  indicator in the first column, `❯`, `!` in shell mode or the agent a teammate view names,
+  then the client's no-break space), the draft's other rows indented past the indicator, and
+  the rule that closes it. The footer is the rows under that rule, down to the first blank
+  row. The conversation is above the box and the draft inside it, so the banner's words in a
+  reply, a quoted log line, a tool's output or the prompt never count. Neither do the
+  background tasks, listed after that blank row. A dialog drawn in the box's place (a
+  permission request, a plan to approve) has a top rule only, its title and body indented
+  under it. It opens no box, so nothing it quotes counts, and the same goes for a picker or
+  a question. The match is the client's
+  own shape: `Critical memory usage (<size>)`, with the size in the client's format (`8.3GB`,
+  `12GB`, `900MB`), then ` — restart and resume with claude --continue` with its em dash,
+  whole or cut at an ellipsis. A hyphen or an en dash after the size is not the banner. The
+  banner is the notification column's last line, so it ends its row: only the client's own
+  pills may follow it, a stashed prompt's (`› stashed`) and an active goal's
+  (`◎ /goal active (5m)`). The banner can be on the mode line's row or, when the pane is too
+  narrow, on a footer row of its own (the notification column wraps). It can also directly
+  follow the mode line, which is then cut short too. A row of the background-task list never
+  counts, even with no blank row above it: it starts with the selection pointer or two spaces,
+  an agent's tree connector, then the task's bullet (`◯`, `⏺` or `●` for the task viewed,
+  `⏸` for a paused workflow), and a task's name and description are the model's own words.
+  Escape sequences are ignored, and wrapped rows are joined. A banner cut before its size
+  closes goes unseen.
+- **When:** every `CLAUDE_MULTIACC_AR_MEMORY_SCAN` seconds (30; `0` turns the memory watch
+  off), and never before the launch is `CLAUDE_MULTIACC_AR_MEMORY_MIN_UPTIME` old (900 s).
+  A resumed session can come back as heavy as it left, and this keeps it out of a restart
+  loop.
+- **Then the main thread's path:** grace, budgets, probe, hold for want of room, the
+  relaunch file, the stop and the typed relaunch, with these differences:
+  - **Any account may take the session**, the one it is on included, exactly as after a
+    crash. Nothing is marked on the old account and the chain avoids nothing new: the shim
+    runs ordinary selection.
+  - **The transcript's own verdict goes first.** A usage limit, login failure or API error
+    pending at the same time moves the session instead, which also ends the heavy process.
+  - **The main thread's work in flight is waited for:** a request with nothing back, a reply
+    still streaming, a tool with no result (the same rules as for an agent's verdict), and a
+    compaction under way. `/compact` is the banner's other remedy, and the transcript shows
+    nothing of it until it is done, so the pane's spinner above the prompt box counts:
+    `Compacting conversation…`. The wait is logged once as
+    `hold reason=main-<request|stream|tool|compact>`. Each wait is capped at
+    `CLAUDE_MULTIACC_AR_MEMORY_BUSY_CAP` (600 s), since the process may not last much
+    longer. The cap counts from the first reading that found that work, not from the
+    detection. Time the verdict spent held for want of room, or behind a transcript verdict,
+    uses none of it, and work started later gets a full cap of its own. A main thread found
+    idle ends its wait. Background agents and workflows are not waited for: they run
+    continuously, and they end with the session either way.
+  - **The banner going away ends the verdict.** After `/compact` the heap can fall back under
+    the line. The pane is read again on each scan and once more right before the stop. A
+    banner that comes and goes (a heap near the line, a pane read that fails) changes only the
+    memory verdict: a transcript verdict pending meanwhile keeps its own probes and hold lines.
+  - **A check that refuses the stop drops only the memory verdict.** The checks before any
+    stop still apply: the pane and its shell, the client in the foreground and leading its
+    process group, no other client holding the session, its directory, no synchronized panes
+    or stuck mode, and the relaunch file written. When one refuses a usage limit, a login
+    failure or a crash, the watcher gives up, as always. When one refuses a memory restart,
+    the watcher logs `giveup reason=memory-<why> class=memory` once and drops the verdict.
+    It then does not read the pane for `CLAUDE_MULTIACC_AR_MEMORY_BACKOFF` seconds (600), and
+    keeps watching the session for everything else.
+  - **At most `CLAUDE_MULTIACC_AR_MEMORY_PER_HOUR` (2) memory restarts per chain per hour.**
+    Beyond that the watcher logs `giveup reason=memory-budget class=memory` once and leaves
+    that process's memory alone, but keeps watching for every other verdict.
+  - **The prompt says why:** "…restarted automatically because the previous process reached
+    critical memory usage (8.3GB). …", without "on another account".
+- **A client that ignores SIGTERM** (the 8.3GB one did, for over 15 s) gets SIGKILL after
+  `CLAUDE_MULTIACC_AR_TERM_GRACE` (10 s), like any stop. The relaunch is typed once the
+  client and the processes recorded with it are gone and the shell is back. Tearing a huge
+  process down can take the kernel a few seconds; `CLAUDE_MULTIACC_AR_PANE_WAIT` (15 s)
+  allows for that.
+- **An optional backstop,** off by default: with `CLAUDE_MULTIACC_AR_MEMORY_LIMIT_MB=<MB>`
+  set, the client's own memory at or over that many megabytes counts too
+  (`code=memory_limit src=process`), read without a child process: its phys_footprint
+  (Activity Monitor's Memory) through libproc on macOS, VmRSS + VmSwap on Linux. That is
+  the whole process: more than the heap the banner measures, so set the limit well above
+  2.5 GiB.
 
 ## What gets a watcher
 
@@ -266,7 +511,8 @@ launch.
     `--effort <e>`, `--permission-mode <m>`, and at most one prompt argument that
     contains a space.
   - **codex:** `--dangerously-bypass-approvals-and-sandbox`, `--yolo`, `--no-daemon`,
-    `-m` / `--model <m>`, `resume <uuid>|--last`, and at most one prompt that contains a
+    `-m` / `--model <m>`, `-c model_reasoning_effort=<level>` (the only `-c` accepted,
+    with a lowercase level), `resume <uuid>|--last`, and at most one prompt that contains a
     space. The conservative pair `--sandbox read-only --ask-for-approval on-request`
     is also supported; partial, conflicting or other sandbox/approval combinations are not.
   - **Anything else means no watcher.** That includes `-p` (for codex, `-p` is
@@ -293,13 +539,14 @@ tokens.
 | Event | Written by | Meaning |
 | --- | --- | --- |
 | `watch` | watcher | supervision started for a pid |
-| `detect` | watcher | a classified error is pending |
+| `detect` | watcher | a classified error is pending (`src=sidechain agent=<id>` when a subagent's transcript recorded it); `class=memory code=critical_memory size=<size> src=pane` for the client's memory banner (`code=memory_limit src=process` for the opt-in backstop) |
 | `never` | watcher | an error auto-resume does not handle; ignored |
-| `hold` | watcher | no other account has headroom, so nothing is stopped |
-| `switch` | watcher | stopped the session and typed the relaunch (`from=`, `class=`, `sid=`, `depth=`) |
+| `hold` | watcher | the verdict stands but nothing is stopped yet: no other account has headroom (`reason=no-room`), a budget is spent, or an agent's or a memory verdict waits for the main thread's own work (`reason=main-request`, `main-stream`, `main-tool`; a memory verdict also `main-compact`) |
+| `switch` | watcher | stopped the session and typed the relaunch (`from=`, `class=`, `sid=`, `depth=`; `model=` / `effort=` when the relaunch pins them; `size=` for a memory restart) |
 | `crash` | watcher | claude ended unexpectedly; relaunching |
-| `giveup` | watcher | could not relaunch safely (`reason=` pane, shell, pgrp, holder, tree, relaunch, …); with `stopped=1` the session was stopped and `resume=` names the command to run |
+| `giveup` | watcher | could not relaunch safely (`reason=` pane, shell, pgrp, holder, tree, relaunch, …); with `stopped=1` the session was stopped and `resume=` names the command to run. `reason=memory-budget class=memory`: memory restarts are over for that process, and the watcher goes on with every other verdict. `reason=memory-<pane, pane-shell, background, pgrp, holder, cwd, sync, mode, write> class=memory`: that check refused a memory restart before anything was stopped; the verdict is dropped, the pane is not read for `MEMORY_BACKOFF` s, and the watcher goes on |
 | `relaunch` | the relaunched shim | consumed the token (`chain=`, `from=`, `class=`, `depth=`) |
+| `trust-failed` | the relaunched codex shim | could not mark its cwd trusted in the picked account (`chain=`, `acct=`); the TUI may ask for folder access |
 
 Cross-provider `switch` records also include `to_provider` and the newly confirmed
 destination conversation's `to_sid`; `sid` continues to identify the source conversation.
@@ -349,12 +596,22 @@ CLAUDE_MULTIACC_AR_PROBE=1 CLAUDE_MULTIACC_AR_AVOID=acct-07:1790000000 claude
   descendants in its process group. Detached work and a pre-existing shared Codex daemon
   may survive; the continuation prompt requires checking before relying on or restarting
   that work. For Claude model-limit and transient errors, the watcher first waits up to
-  15 min for subagent transcripts to go quiet.
+  15 min for subagent transcripts to go quiet. An account verdict a subagent recorded
+  moves the session after the usual 5 s even while the main thread is still running a
+  tool: the account would refuse that thread's next request, and the tool is stopped.
 - **Only the pane's own shell is typed into.** The relaunch goes only to the shell that
   launched the session. A session started from a nested shell or a script, or with
   `exec claude`, gets a watcher that gives up instead of relaunching.
 - **Typeahead is discarded.** Text sitting at the shell prompt when the relaunch is typed
   is cleared.
+- **Critical memory is seen only on screen.** The banner is read from the pane, so it goes
+  unseen while the prompt box is not drawn (the transcript view, a dialog), when the pane is
+  too narrow to show its size, or in a client that words or places it differently. A
+  fullscreen client (`"tui": "fullscreen"`, `CLAUDE_CODE_NO_FLICKER=1`; the pool's accounts
+  run `"tui": "default"`) draws its notifications over the row above the prompt box. That
+  row is among the conversation's, where the banner cannot be told from a reply quoting it,
+  so it is not read. The session then stays as it is; `CLAUDE_MULTIACC_AR_MEMORY_LIMIT_MB`
+  is the backstop for that.
 - **Codex goals do not follow yet.** Codex keeps `/goal` state per account
   (`goals_1.sqlite`), so set the goal again after a codex rotation. Claude restores a goal
   from the transcript on resume.

package/docs/CODEX.md

@@ -208,6 +208,7 @@ codex-accounts list
 codex-accounts status
 codex-accounts verify --quick         # check local auth without inference
 codex-accounts verify                 # real codex exec call per account
+codex-accounts model-catalog show     # the model/effort catalog auto-resume matches with
 codex-accounts --help                 # all account commands and options
 claude-multiacc codex status          # same status command via the npm wrapper
 ```