claude-multiacc 2.0.57 → 2.0.59

package/tests/test_autoresume.py

@@ -83,6 +83,17 @@ def cc_quota(ts, rtype="five_hour", resets=None, **extra):
     return rec
 
 
+def cc_concurrents(ts):
+    """claude 2.1.304's record of the account turning away a request among too many in
+    flight at once (2026-10-20): the generic usage-limit words, and no reset."""
+    info = {"status": "rejected", "rateLimitType": "concurrents", "isUsingOverage": False}
+    return cc_api_error(ts, "rate_limit", "You've hit your usage limit", apiErrorStatus=429,
+                        apiError="usage_limit_reached",
+                        apiErrorParams={"rate_limit_info": info},
+                        quotaLimits=dict(info, unifiedRateLimitFallbackAvailable=False,
+                                         upgradePaths=["overage"]))
+
+
 def cc_system(ts):
     return cc_base(ts, "system", subtype="informational", level="notice", isMeta=False,
                    content="Usage limit reached · continuing automatically at 3:36am "
@@ -104,6 +115,17 @@ def cc_reply(ts, text="Done.", **extra):
     return rec
 
 
+def cc_slash(ts, name="model"):
+    """What a slash command run at the prompt leaves in the main transcript (claude 2.1.303,
+    /model in sessions 5 and 8 on 2026-10-19): a caveat, the command, its output."""
+    return [cc_user(ts, "<local-command-caveat>Caveat: The messages below were generated by "
+                        "the user while running local commands.</local-command-caveat>",
+                    isMeta=True),
+            cc_user(ts, "<command-name>/%s</command-name>\n<command-message>%s</command-message>"
+                        "\n<command-args></command-args>" % (name, name)),
+            cc_user(ts, "<local-command-stdout>Kept model as Opus 5.5</local-command-stdout>")]
+
+
 # ---- codex rollout records (codex 0.156.0 shapes) ------------------------------------
 
 def cx_meta(ts, sid=CX_SID, session_id=None, cwd="/w", originator="codex-tui"):
@@ -217,6 +239,16 @@ class ClaudeClassifierTests(unittest.TestCase):
             self.assertEqual(self.verdict(cc_quota(self.T, rtype, resets=self.T + 60))["class"],
                              "model", rtype)
 
+    def test_a_concurrency_throttle_is_transient(self):
+        # 2026-10-20: read as one model's limit, it kept two sessions off a serving account
+        # for five hours; the account served 700+ requests a minute around those 54
+        v = self.verdict(cc_concurrents(self.T))
+        self.assertEqual((v["class"], v["code"], v["reset"], v["rtype"]),
+                         ("transient", "rate_limit", None, ""))
+        # an agent's is its own: it never moves the session
+        self.assertIsNone(ar.classify_claude_sidechain(dict(cc_concurrents(self.T),
+                                                            isSidechain=True)))
+
     def test_model_limit_without_quota_limits(self):
         for text in ("You've reached your Fable limit. Run /usage-credits to keep going.",
                      "You've reached your Fable limit. Switch to another model to continue."):
@@ -263,9 +295,26 @@ class ClaudeClassifierTests(unittest.TestCase):
     def test_what_counts_as_the_user_typing(self):
         cancel = ("cancel", "user")
         self.assertEqual(ar.classify_claude(cc_user(self.T, "please continue")), cancel)
+        # a slash command that only shows or configures the session is the user too, but one
+        # the tracker tells apart (it ends only a model-scoped or transient verdict), in
+        # either order the client writes its tags
+        for text in ("<command-name>/model</command-name>\n<command-args></command-args>",
+                     "<command-message>model</command-message>\n<command-name>/model"
+                     "</command-name>",
+                     [{"type": "text", "text": " <command-name>/usage</command-name>"}],
+                     "<command-name>/Effort</command-name>\n<command-args>max</command-args>"):
+            self.assertEqual(ar.classify_claude(cc_user(self.T, text)), ("cancel", "command"))
+        for name in ("model", "effort", "mcp", "status", "context", "cost"):
+            self.assertEqual(ar.classify_claude(cc_slash(self.T, name)[1]), ("cancel", "command"))
+        # any other command may be what fixed the account: the user typing, as before
+        for name in ("login", "limit-reset", "usage-credits", "extra-usage", "upgrade",
+                     "rate-limit-options", "config", "fast", "compact", "brand-new-command"):
+            self.assertEqual(ar.classify_claude(cc_slash(self.T, name)[1]), cancel, name)
+        for text in ("<command-message>model</command-message>", "<command-name></command-name>",
+                     "<command-name>/model</command-name"):
+            self.assertEqual(ar.classify_claude(cc_user(self.T, text)), cancel, text)
         self.assertEqual(ar.classify_claude(cc_user(
-            self.T, "<command-name>/model</command-name>\n<command-args></command-args>")),
-            cancel)
+            self.T, "what does <command-name> mean here?")), cancel)
         self.assertEqual(ar.classify_claude(cc_user(
             self.T, [{"type": "text", "text": "look at this"},
                      {"type": "image", "source": {"type": "base64", "data": "AA=="}}])), cancel)
@@ -281,7 +330,7 @@ class ClaudeClassifierTests(unittest.TestCase):
             cc_user(self.T, "This session is being continued from a previous conversation",
                     isCompactSummary=True),
             cc_user(self.T, []),
-        ]
+        ] + [cc_slash(self.T)[0], cc_slash(self.T)[2]]
         for rec in not_human:
             self.assertIsNone(ar.classify_claude(rec), rec["message"])
 
@@ -334,6 +383,56 @@ class ClaudeTrackerTests(unittest.TestCase):
         self.assertIsNone(tr.feed(cc_user(self.LAUNCHED - 60, "old"), 3))
         self.assertIsNotNone(tr.pending)
 
+    def test_a_slash_command_ends_only_a_model_scoped_or_transient_verdict(self):
+        # the ACCOUNT's verdicts outlive /model (sessions 5 and 8, 2026-10-19): it is just as
+        # limited afterwards
+        for err in (cc_quota(self.LAUNCHED + 1, resets=self.LAUNCHED + 99),
+                    cc_quota(self.LAUNCHED + 1, "seven_day"),
+                    cc_api_error(self.LAUNCHED + 1, "authentication_failed"),
+                    cc_api_error(self.LAUNCHED + 1, "oauth_org_not_allowed"),
+                    cc_api_error(self.LAUNCHED + 1, "billing_error")):
+            with self.subTest(verdict=err["error"]):
+                tr = self.tracker()
+                tr.feed(err, 1)
+                pending = tr.pending
+                self.assertIn(pending["class"], ar.ACCOUNT_CLASSES)
+                for rec in cc_slash(self.LAUNCHED + 2) + cc_slash(self.LAUNCHED + 3, "usage"):
+                    self.assertIsNone(tr.feed(rec, 2))
+                self.assertEqual((tr.pending, tr.pending_since, tr.cleared), (pending, 1, 0.0))
+                # a prompt the user types still ends it, as before
+                self.assertEqual(tr.feed(cc_user(self.LAUNCHED + 4, "wait, I'll switch"), 4),
+                                 ("cancel", "user"))
+                self.assertIsNone(tr.pending)
+        # /model is how one handles a MODEL's limit; a failed turn ends with any input
+        for err in (cc_quota(self.LAUNCHED + 1, "seven_day_opus"),
+                    cc_api_error(self.LAUNCHED + 1, "rate_limit", "You've reached your Fable "
+                                 "limit. Switch to another model to continue."),
+                    cc_api_error(self.LAUNCHED + 1, "overloaded")):
+            with self.subTest(verdict=err["error"]):
+                tr = self.tracker()
+                tr.feed(err, 1)
+                self.assertIn(tr.pending["class"], ("model", "transient"))
+                self.assertEqual(tr.feed(cc_slash(self.LAUNCHED + 2)[1], 2), ("cancel", "command"))
+                self.assertIsNone(tr.pending)
+
+    def test_a_command_that_can_fix_the_account_ends_its_verdict(self):
+        # "Not logged in · Please run /login": /login, or /limit-reset after the limit, is
+        # the user fixing the ACCOUNT — like a typed prompt, and like any command not known
+        # to leave it as it was
+        for err, name in ((cc_api_error(self.LAUNCHED + 1, "authentication_failed",
+                                        "Not logged in · Please run /login"), "login"),
+                          (cc_quota(self.LAUNCHED + 1, resets=self.LAUNCHED + 99), "limit-reset"),
+                          (cc_quota(self.LAUNCHED + 1, "seven_day"), "extra-usage"),
+                          (cc_api_error(self.LAUNCHED + 1, "oauth_org_not_allowed"), "login"),
+                          (cc_quota(self.LAUNCHED + 1, resets=self.LAUNCHED + 99), "plugin:fix")):
+            with self.subTest(verdict=err["error"], command=name):
+                tr = self.tracker()
+                tr.feed(err, 1)
+                self.assertIsNone(tr.feed(cc_slash(self.LAUNCHED + 2, name)[0], 2))  # the caveat
+                self.assertEqual(tr.feed(cc_slash(self.LAUNCHED + 2, name)[1], 2),
+                                 ("cancel", "user"))
+                self.assertIsNone(tr.pending)
+
     def test_pending_since_restarts_only_on_a_class_change(self):
         tr = self.tracker()
         tr.feed(cc_quota(self.LAUNCHED + 1), 10)
@@ -506,8 +605,8 @@ class ArgvTests(unittest.TestCase):
         self.assertEqual(self.rl("claude", []), ["--resume", SID, p])
 
     def test_claude_model_is_only_the_launchs_own(self):
-        # Claude restores the session's model on --resume ([1m] included); an added
-        # --model would switch that off. An explicit one from the launch is kept as is.
+        # Claude restores the session's model on --resume ([1m] included), so no --model is
+        # added, and an explicit one from the launch is kept as is.
         p = ar.resume_prompt("model")
         self.assertEqual(self.rl("claude", ["hello there"], "model"), ["--resume", SID, p])
         self.assertEqual(self.rl("claude", ["--model", "sonnet"], "model"),
@@ -1248,6 +1347,40 @@ class ClaudeWatcherTests(PoolCase):
         self.assertTrue(kv["hist"].startswith("quota:%d,auth:" % (self.t0 - 7200)))
         self.assertIn("chain=ChainId1", self.log_lines()[0])
 
+    def test_the_relaunch_names_the_credential_its_run_carried(self):
+        # The shim launched this run on the portable token (via=token in its state). /clear
+        # then has the same process run a new session id, which no capture of the shim ever
+        # tagged: its auth failure is still the token's, and the relaunch file says so.
+        state = self.write_state(["-c"])
+        with open(state, "a") as fh:
+            fh.write("via=token\n")
+        self.registry()
+        self.transcript([cc_user(self.launched + 1, "hello")])
+        w, r = self.watcher(state)
+        r.at(self.t0 + 1, lambda: self.registry(sid=SID2))
+        r.at(self.t0 + 3, lambda: self.transcript([cc_api_error(
+            self.t0 + 3, "authentication_failed", "Not logged in · Please run /login")], sid=SID2))
+        w.run()
+        kv, _ = self.relaunch_of(r)
+        self.assertEqual((kv["class"], kv["sid"], kv["via"]), ("auth", SID2, "token"))
+
+    def test_the_state_names_a_credential_or_nothing(self):
+        for raw, want in (("token", "token"), ("login", "login"), ("", ""), ("TOKEN", ""),
+                          ("token x", "")):
+            state = self.write_state(["-c"])
+            with open(state, "a") as fh:
+                fh.write("via=%s\n" % raw)
+            self.assertEqual(ar.load_state(state)["via"], want, raw)
+        # a shim from before the field: nothing is named, and the relaunch names nothing
+        state = self.write_state(["-c"])
+        self.assertEqual(ar.load_state(state)["via"], "")
+        self.registry()
+        self.transcript([cc_api_error(self.t0, "authentication_failed", "Not logged in")])
+        w, r = self.watcher(state)
+        w.run()
+        kv, _ = self.relaunch_of(r)
+        self.assertNotIn("via", kv)
+
     def test_old_rejection_in_a_resumed_transcript_does_not_fire(self):
         state = self.write_state(["--resume", SID])
         self.registry()
@@ -1314,6 +1447,68 @@ class ClaudeWatcherTests(PoolCase):
         self.assertEqual(len(r.probes), 1)
         self.assertEqual((r.signals, r.sends, self.relaunch_files()), ([], [], []))
 
+    def test_a_slash_command_moves_on_only_from_a_model_scoped_limit(self):
+        reset = int(self.t0) + 999
+        for err, moved in ((cc_quota(self.t0, resets=reset), True),
+                           (cc_api_error(self.t0, "rate_limit", "You've reached your Fable "
+                                         "limit. Switch to another model"), False)):
+            with self.subTest(moved=moved):
+                log = self.root / "selection.log"
+                if log.exists():
+                    log.unlink()
+                state = self.write_state([])
+                reg = self.registry()
+                tpath = self.transcript([err])
+                w, r = self.watcher(state)
+                # the user runs /model before GRACE runs out, and later leaves with /exit
+                r.at(self.t0 + 1.5, lambda tpath=tpath: append(tpath, cc_slash(self.t0 + 1)))
+                r.at(self.t0 + 30, lambda reg=reg, r=r: (reg.unlink() if reg.exists() else None,
+                                                         r.exit(self.PID)))
+                self.assertEqual(w.run(), 0)
+                self.assertEqual(len(r.probes), int(moved))
+                self.assertEqual(self.events(), ["watch", "detect"] + ["switch"] * moved)
+                if moved:
+                    self.assertEqual(self.relaunch_of(r)[0]["class"], "quota")
+                tpath.unlink()
+
+    def test_a_command_that_fixes_the_account_keeps_the_session(self):
+        # /login 2 s after "Not logged in · Please run /login" (the TUI must not be stopped
+        # mid-login, nor the account being logged back in parked); /limit-reset while the
+        # watcher holds for want of room, before room appears; a watcher restarted onto a
+        # limit the user reset half an hour ago
+        reset = int(self.t0) + 9000
+        cases = ((cc_api_error(self.t0, "authentication_failed",
+                               "Not logged in · Please run /login"), "login", 2, False),
+                 (cc_quota(self.t0, resets=reset), "limit-reset", 8, False),
+                 (cc_quota(self.t0 - 1800, resets=reset), "limit-reset", -1790, True))
+        for err, name, after, restarted in cases:
+            with self.subTest(command=name, restarted=restarted):
+                log = self.root / "selection.log"
+                if log.exists():
+                    log.unlink()
+                self.launched = int(self.t0) - (3600 if restarted else 5)
+                state = self.write_state([])
+                reg = self.registry()
+                tpath = self.transcript([cc_user(self.launched + 1, "go"),
+                                         cc_reply(self.launched + 2, "ok"), err]
+                                        + (cc_slash(self.t0 + after, name) if after < 0 else []))
+                w, r = self.watcher(state, {"CLAUDE_MULTIACC_AR_HOLD_REPROBE": "10"})
+                held = name == "limit-reset" and not restarted
+                if held:
+                    r.probe_out = "pick=acct-01 tier=soft\n"  # nowhere to go: hold
+                    r.at(self.t0 + 9, lambda r=r: setattr(r, "probe_out",
+                                                          "pick=acct-02 tier=eligible\n"))
+                if after > 0:
+                    r.at(self.t0 + after, lambda tpath=tpath, at=self.t0 + after, name=name:
+                         append(tpath, cc_slash(at, name)))
+                r.at(self.t0 + 40, lambda reg=reg, r=r: (reg.unlink() if reg.exists() else None,
+                                                         r.exit(self.PID)))
+                self.assertEqual(w.run(), 0)
+                self.assertEqual((len(r.probes), r.signals, r.sends, self.relaunch_files()),
+                                 (int(held), [], [], []))
+                self.assertEqual(self.events(), ["watch", "detect"] + ["hold"] * held)
+                tpath.unlink()
+
     def test_kill_switch_file_reaches_a_running_watcher(self):
         state = self.write_state([])
         self.registry()
@@ -1354,12 +1549,14 @@ class ClaudeWatcherTests(PoolCase):
         self.assertEqual(w.run(), 0)
         self.assertEqual((r.probes, r.signals), ([], []))
         kv, argv = self.relaunch_of(r)
+        # the transcript's last reply names its model and no effort: Claude restores the model
         self.assertEqual(argv, ["--dangerously-skip-permissions", "--resume", SID,
                                 ar.resume_prompt("crash")])
         self.assertEqual((kv["class"], kv["acct"], kv["avoid"], kv["depth"]),
                          ("crash", "acct-01", "acct-05:%d" % (self.t0 + 900), "1"))
         self.assert_sequence(r)
         self.assertEqual(self.events(), ["watch", "crash", "switch"])
+        self.assertTrue(self.log_lines()[-1].endswith(" probe=-"))
 
     def test_a_clean_exit_or_an_early_death_is_final(self):
         state = self.write_state([])
@@ -2273,9 +2470,12 @@ class CliTests(PoolCase):
                               timeout=timeout, universal_newlines=True)
 
     def test_classify(self):
-        path = self.transcript([cc_quota(self.t0 - 10000, resets=1790123817),
+        # Resets in the future (the classifier drops a quota verdict whose reset has passed,
+        # as the watcher does: the last case below).
+        week = future_reset(self.t0)
+        path = self.transcript([cc_quota(self.t0 - 10000, resets=week - 86400),
                                 cc_api_error(self.t0, "invalid_request"),
-                                cc_quota(self.t0, "seven_day", resets=1790372787),
+                                cc_quota(self.t0, "seven_day", resets=week),
                                 cc_user(self.t0 + 1, "go"),
                                 cc_api_error(self.t0 + 2, "authentication_failed")])
         out = self.cli("classify", "--provider", "claude", str(path),
@@ -2285,10 +2485,17 @@ class CliTests(PoolCase):
         self.assertEqual([e["kind"] for e in doc["events"]],
                          ["never", "verdict", "cancel", "verdict"])
         self.assertEqual((doc["events"][1]["class"], doc["events"][1]["rtype"],
-                          doc["events"][1]["reset"]), ("quota", "seven_day", 1790372787))
+                          doc["events"][1]["reset"]), ("quota", "seven_day", week))
         self.assertEqual(doc["pending"]["class"], "auth")
         doc = json.loads(self.cli("classify", "--provider", "claude", str(path)).stdout)
         self.assertEqual(doc["events"][0]["kind"], "verdict")  # no --since: everything counts
+        # a limit whose reset has passed is no verdict; one with no reset still is
+        lifted = self.tmp / "lifted.jsonl"
+        lifted.write_text(jl([cc_quota(self.t0 - 600, resets=int(self.t0) - 60),
+                              cc_quota(self.t0 - 500)]))
+        doc = json.loads(self.cli("classify", "--provider", "claude", str(lifted)).stdout)
+        self.assertEqual([(e["kind"], e["class"], e["reset"]) for e in doc["events"]],
+                         [("verdict", "quota", None)])
 
     def test_classify_codex(self):
         reset = future_reset(self.t0)

package/tests/test_autoresume_catalog.py

@@ -0,0 +1,226 @@
+"""lib/model_catalog.py and lib/model_match.py: the catalog and the level matching."""
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "lib"))
+import model_catalog as mc  # noqa: E402
+import model_match as mm  # noqa: E402
+
+LEVELS = ["low", "medium", "high", "xhigh", "max"]
+CODEX_LEVELS = LEVELS + ["ultra"]
+
+
+def entry(family, version, efforts, default, listed=True, upgrade=None):
+    return {"family": family, "version": version, "efforts": efforts, "default_effort": default,
+            "listed": listed, "upgrade": upgrade}
+
+
+CATALOG = {"schema": 1,
+           "claude": {"efforts": LEVELS, "families": {"haiku": 2, "sonnet": 3, "opus": 4, "fable": 5, "mythos": 5},
+                      "models": {"claude-fable-5-1": entry("fable", [5, 1], LEVELS, "high"),
+                                 "claude-opus-5-5": entry("opus", [5, 5], LEVELS, "medium"),
+                                 "claude-sonnet-5-5": entry("sonnet", [5, 5], LEVELS, "medium"),
+                                 "claude-haiku-5-5": entry("haiku", [5, 5], LEVELS, "medium"),
+                                 "claude-opus-4-6": entry("opus", [4, 6], LEVELS[:3] + ["max"], "high", False),
+                                 "claude-sonnet-4-6": entry("sonnet", [4, 6], LEVELS[:3] + ["max"], "high", False)}},
+           "codex": {"efforts": ["none", "minimal"] + CODEX_LEVELS,
+                     "families": {"luna": 1, "terra": 2, "sol": 3, "astra": 4},
+                     "models": {"gpt-6.1-sol": entry("sol", [6, 1], CODEX_LEVELS, "low"),
+                                "gpt-6-astra": entry("astra", [6], CODEX_LEVELS, "medium"),
+                                "gpt-6-sol": entry("sol", [6], CODEX_LEVELS, "medium"),
+                                "gpt-6-luna": entry("luna", [6], LEVELS, "medium"),
+                                "gpt-5.6-terra": entry("terra", [5, 6], CODEX_LEVELS, "medium"),
+                                "gpt-5.5": entry(None, [5, 5], LEVELS[:4], "medium", False, "gpt-6.1-sol")}}}
+
+
+class MatchTests(unittest.TestCase):
+    def match(self, source, model, effort, target):
+        got = mm.resume_settings(source, {"model": model, "effort": effort}, target, CATALOG)
+        return got["model"], got["effort"]
+
+    def test_current_lineup_is_the_newest_listed_model_per_family(self):
+        # terra's newest is a 5.x: still the terra level (launches are staggered)
+        self.assertEqual(mm.current_models(CATALOG, "codex"),
+                         {"sol": "gpt-6.1-sol", "astra": "gpt-6-astra", "luna": "gpt-6-luna", "terra": "gpt-5.6-terra"})
+        self.assertEqual(mm.current_models(CATALOG, "claude"),
+                         {"fable": "claude-fable-5-1", "opus": "claude-opus-5-5", "sonnet": "claude-sonnet-5-5",
+                          "haiku": "claude-haiku-5-5"})
+
+    def test_models_match_by_level(self):
+        # the operator's map (2026-10-14): astra -> opus, sol -> sonnet, terra and luna -> haiku ...
+        self.assertEqual(self.match("codex", "gpt-6-astra", "ultra", "claude"), ("claude-opus-5-5", "max"))
+        self.assertEqual(self.match("codex", "gpt-6.1-sol", "high", "claude"), ("claude-sonnet-5-5", "high"))
+        self.assertEqual(self.match("codex", "gpt-6-sol", "xhigh", "claude"), ("claude-sonnet-5-5", "xhigh"))
+        self.assertEqual(self.match("codex", "gpt-5.6-terra", "none", "claude"), ("claude-haiku-5-5", "low"))
+        self.assertEqual(self.match("codex", "gpt-6-luna", "minimal", "claude"), ("claude-haiku-5-5", "low"))
+        # ... and fable, mythos and opus -> astra, sonnet -> sol, haiku -> terra
+        self.assertEqual(self.match("claude", "claude-fable-5-1", "max", "codex"), ("gpt-6-astra", "max"))
+        self.assertEqual(self.match("claude", "claude-opus-5-5[1m]", "xhigh", "codex"), ("gpt-6-astra", "xhigh"))
+        self.assertEqual(self.match("claude", "claude-opus-4-6", "medium", "codex"), ("gpt-6-astra", "medium"))
+        self.assertEqual(self.match("claude", "claude-sonnet-5-5", "high", "codex"), ("gpt-6.1-sol", "high"))
+        self.assertEqual(self.match("claude", "claude-haiku-5-5", "low", "codex"), ("gpt-5.6-terra", "low"))
+        # a retiring model counts as its upgrade; an unknown one is left to the destination
+        self.assertEqual(self.match("codex", "gpt-5.5", "xhigh", "claude"), ("claude-sonnet-5-5", "xhigh"))
+        self.assertEqual(self.match("codex", "codex-auto-review", "high", "claude"), (None, "high"))
+        self.assertEqual(self.match("claude", "claude-mythos-9", "max", "codex"), ("gpt-6-astra", "max"))
+        self.assertEqual(self.match("codex", None, None, "claude"), (None, None))
+
+    def test_effort_is_clamped_to_what_the_destination_model_supports(self):
+        # gpt-6-luna has no ultra: max, the nearest level below
+        self.assertEqual(mm.match_effort(CATALOG, "claude", "max", "codex", "gpt-6-luna"), "max")
+        self.assertEqual(mm.match_effort(CATALOG, "codex", "ultra", "codex", "gpt-6-luna"), "max")
+        self.assertEqual(mm.match_effort(CATALOG, "codex", "xhigh", "claude", "claude-opus-4-6"), "high")
+        self.assertEqual(mm.match_effort(CATALOG, "codex", "ultra", "claude", "claude-sonnet-4-6"), "max")
+        self.assertEqual(mm.match_effort(CATALOG, "claude", "xhigh", "codex", "gpt-5.5"), "xhigh")
+        self.assertEqual(mm.match_effort(CATALOG, "codex", "persistent", "claude", "claude-opus-5-5"), None)
+        self.assertEqual(mm.match_effort(CATALOG, "claude", "high", "claude", "claude-unknown-9"), "high")
+
+    def test_same_provider_passes_the_session_through(self):
+        self.assertEqual(self.match("claude", "claude-opus-5-5[1m]", "max", "claude"), ("claude-opus-5-5[1m]", "max"))
+        self.assertEqual(self.match("claude", "claude-opus-5-5", None, "claude"), ("claude-opus-5-5", None))
+        # codex needs both flags or none: an unset effort becomes the model's catalog default
+        self.assertEqual(self.match("codex", "gpt-6-astra", None, "codex"), ("gpt-6-astra", "medium"))
+        self.assertEqual(self.match("codex", "gpt-unknown", None, "codex"), ("gpt-unknown", None))
+
+    def test_flags(self):
+        self.assertEqual(mm.settings_flags("claude", "claude-opus-5-5[1m]", "max"),
+                         ["--model", "claude-opus-5-5[1m]", "--effort", "max"])
+        self.assertEqual(mm.settings_flags("claude", None, "max"), ["--effort", "max"])
+        self.assertEqual(mm.settings_flags("claude", "claude-opus-5-5", None), ["--model", "claude-opus-5-5"])
+        self.assertEqual(mm.settings_flags("codex", "gpt-6-astra", "ultra"),
+                         ["-m", "gpt-6-astra", "-c", "model_reasoning_effort=ultra"])
+        self.assertEqual(mm.settings_flags("codex", "gpt-6-astra", None), [])
+        self.assertEqual(mm.settings_flags("codex", None, "high"), [])
+        self.assertEqual(mm.settings_flags("gemini", "x", "y"), [])
+
+
+class CatalogTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp(prefix="cat-"))
+        self.addCleanup(shutil.rmtree, str(self.tmp), True)
+        self.roots = {"claude": str(self.tmp / "claude"), "codex": str(self.tmp / "codex")}
+        for root in self.roots.values():
+            os.makedirs(os.path.join(root, "acct-01"))
+
+    def codex_cache(self, fetched, models, acct="acct-01"):
+        doc = {"fetched_at": fetched, "etag": "x", "client_version": "0.162.1", "identity": "y",
+               "models": [{"slug": slug, "visibility": "list" if listed else "hide", "priority": 1,
+                           "default_reasoning_level": default,
+                           "supported_reasoning_levels": [{"effort": e, "description": ""} for e in efforts],
+                           "upgrade": {"model": upgrade} if upgrade else None, "model_messages": {"x": "y" * 10}}
+                          for slug, listed, default, efforts, upgrade in models]}
+        path = Path(self.roots["codex"]) / acct / "models_cache.json"
+        path.write_text(json.dumps(doc))
+        return path
+
+    def claude_cache(self, fetched_ms, models, name="tok-abc-cc.json"):
+        rows = [{"id": mid, "section": section, "thinking": {"type": "effort",
+                 "effort_options": [{"id": e, "name": e} for e in efforts]}} for mid, section, efforts, _ in models]
+        state = {"model": models[0][0], "thinking_by_model": [{"id": mid, "thinking": {"type": "effort", "effort": d}}
+                                                              for mid, _, _, d in models]}
+        doc = {"version": 2, "fetchedAt": fetched_ms, "staleAt": fetched_ms + 3600000,
+               "catalog": {"surface": "cc", "config": {"id": "cc", "models": rows}, "state": state}}
+        directory = Path(self.roots["claude"]) / "acct-01" / "cache" / "model-catalog"
+        directory.mkdir(parents=True, exist_ok=True)
+        (directory / name).write_text(json.dumps(doc))
+
+    def test_shipped_catalog_is_well_formed(self):
+        shipped = json.loads(Path(mc.SHIPPED).read_text())
+        for provider in ("claude", "codex"):
+            self.assertEqual(shipped[provider]["efforts"][-5:], LEVELS if provider == "claude" else CODEX_LEVELS[-5:])
+            self.assertTrue(shipped[provider]["families"])
+            self.assertTrue(shipped[provider]["models"])
+            for model, item in shipped[provider]["models"].items():
+                self.assertEqual(sorted(item), ["default_effort", "efforts", "family", "listed", "upgrade", "version"],
+                                 model)
+        current = mm.current_models(shipped, "claude")
+        self.assertEqual(sorted(current), ["fable", "haiku", "opus", "sonnet"])
+        self.assertEqual(sorted(mm.current_models(shipped, "codex")), ["astra", "luna", "sol", "terra"])
+
+    def test_live_caches_win_over_the_shipped_file_when_newer(self):
+        self.codex_cache("2099-01-01T00:00:00.000000Z",
+                         [("gpt-9-astra", True, "high", CODEX_LEVELS, None),
+                          ("gpt-6-astra", False, "medium", CODEX_LEVELS, "gpt-9-astra")])
+        self.claude_cache(4102444800000, [("claude-fable-9", "main", LEVELS, "xhigh"),
+                                          ("claude-haiku-5-5", "overflow", LEVELS, "medium")])
+        catalog = mc.load(self.roots)
+        self.assertEqual(catalog["codex"]["fetched_at"], "2099-01-01T00:00:00Z")
+        self.assertEqual(catalog["codex"]["models"]["gpt-9-astra"],
+                         entry("astra", [9], CODEX_LEVELS, "high"))
+        self.assertEqual(catalog["codex"]["models"]["gpt-6-astra"]["upgrade"], "gpt-9-astra")
+        self.assertEqual(catalog["claude"]["models"]["claude-fable-9"], entry("fable", [9], LEVELS, "xhigh"))
+        self.assertFalse(catalog["claude"]["models"]["claude-haiku-5-5"]["listed"])
+        # structure always comes from the shipped file
+        self.assertEqual(catalog["claude"]["efforts"], LEVELS)
+        self.assertEqual(catalog["codex"]["families"]["astra"], 4)
+        self.assertEqual(mm.current_models(catalog, "codex"), {"astra": "gpt-9-astra"})
+        got = mm.resume_settings("claude", {"model": "claude-fable-9", "effort": "max"}, "codex", catalog)
+        self.assertEqual(got, {"model": "gpt-9-astra", "effort": "max"})
+
+    def test_older_caches_and_junk_lose_to_the_shipped_file(self):
+        self.codex_cache("2000-01-01T00:00:00Z", [("gpt-1-astra", True, "low", LEVELS, None)])
+        (Path(self.roots["codex"]) / "acct-01" / "models_cache.json").write_text("{not json")
+        self.claude_cache(946684800000, [("claude-opus-1", "main", LEVELS, "high")])
+        catalog = mc.load(self.roots)
+        shipped = json.loads(Path(mc.SHIPPED).read_text())
+        self.assertEqual(catalog["codex"]["models"], shipped["codex"]["models"])
+        self.assertEqual(catalog["claude"]["models"], shipped["claude"]["models"])
+        self.assertEqual(mc.load(None)["claude"]["models"], shipped["claude"]["models"])
+
+    def test_refresh_writes_each_pool_root_atomically_and_honours_if_stale(self):
+        self.codex_cache("2099-01-01T00:00:00Z", [("gpt-9-astra", True, "high", CODEX_LEVELS, None)])
+        written = mc.refresh(self.roots)
+        self.assertEqual(sorted(written), sorted(os.path.join(r, mc.OVERLAY) for r in self.roots.values()))
+        doc = json.loads(Path(written[0]).read_text())
+        self.assertEqual(doc["codex"]["models"]["gpt-9-astra"]["default_effort"], "high")
+        self.assertIn("generated_at", doc)
+        self.assertEqual(sorted(os.listdir(self.roots["codex"])), ["acct-01", mc.OVERLAY])
+        self.assertEqual(mc.refresh(self.roots, if_stale=True), [])
+        os.utime(written[0], (0, 0))
+        self.assertEqual(mc.refresh(self.roots, if_stale=True), [written[0]])
+        # the overlay is itself a source for the next load, until a cache is newer
+        shutil.rmtree(os.path.join(self.roots["codex"], "acct-01"))
+        self.assertIn("gpt-9-astra", mc.load(self.roots)["codex"]["models"])
+        self.assertEqual(mc.refresh({"codex": str(self.tmp / "nope")}), [])
+
+    def test_an_unset_root_is_not_searched_from_the_cwd(self):
+        here = self.tmp / "cwd"
+        os.makedirs(str(here / "acct-01"))
+        (here / "acct-01" / "models_cache.json").write_text(json.dumps(
+            {"fetched_at": "2099-01-01T00:00:00Z", "models": [{"slug": "gpt-9-luna", "visibility": "list"}]}))
+        self.addCleanup(os.chdir, os.getcwd())
+        os.chdir(str(here))
+        shipped = json.loads(Path(mc.SHIPPED).read_text())
+        self.assertEqual(mc.load({"claude": self.roots["claude"]})["codex"]["models"], shipped["codex"]["models"])
+
+    def test_a_failed_write_leaves_no_scratch_file(self):
+        os.makedirs(os.path.join(self.roots["codex"], mc.OVERLAY))  # os.replace onto a directory fails
+        self.assertEqual(mc.refresh(self.roots), [os.path.join(self.roots["claude"], mc.OVERLAY)])
+        self.assertEqual(sorted(os.listdir(self.roots["codex"])), ["acct-01", mc.OVERLAY])
+
+    def test_cli(self):
+        script = str(ROOT / "lib/model_catalog.py")
+        out = subprocess.run([sys.executable, "-I", script, "refresh", "--codex-root", self.roots["codex"],
+                              "--claude-root", self.roots["claude"]], capture_output=True, text=True)
+        self.assertEqual(out.returncode, 0, out.stderr)
+        self.assertEqual(sorted(out.stdout.split()), sorted(os.path.join(r, mc.OVERLAY) for r in self.roots.values()))
+        out = subprocess.run([sys.executable, "-I", script, "show"], capture_output=True, text=True)
+        self.assertEqual(out.returncode, 0)
+        self.assertEqual(json.loads(out.stdout)["claude"]["efforts"], LEVELS)
+        for args in ([], ["bogus"], ["refresh", "--codex-root"], ["refresh", "show"]):
+            self.assertEqual(subprocess.run([sys.executable, "-I", script] + args, capture_output=True).returncode, 2)
+        out = subprocess.run([sys.executable, "-I", script, "refresh", "--codex-root", str(self.tmp / "nope")],
+                             capture_output=True, text=True)
+        self.assertEqual(out.returncode, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()