relay-codex 0.6.0 → 0.7.0

package/README.md

@@ -68,6 +68,9 @@ at Mac login. `relay menubar --no-startup --configure-only` disables login start
 Use a session's menu to switch accounts after its work finishes. Account menus can
 enable or disable future routing without stopping current tasks. Actions show
 their result, and stopped workers offer a restart.
+Account menus also show earned usage resets when available. Choose **Use available
+reset…** and confirm to spend one; Relay refreshes allowance afterward. Recovery
+never spends these resets automatically.
 
 For tab completion in Zsh, run `source <(relay completion zsh)` after `compinit`.
 Bash users can run `source <(relay completion bash)`. Add the same line to your

package/docs/commands.md

@@ -40,6 +40,7 @@ relay account priority personal 10
 relay account cap personal 2
 relay account models personal YOUR_MODEL
 relay account reauth personal
+relay account reset personal --yes
 relay account remove personal
 ```
 
@@ -49,6 +50,24 @@ label, unique email, or chosen display name. Renaming keeps the login usable.
 A session cap of zero means unlimited. Removing an account retains its login
 unless you request `--revoke`.
 
+The account menu shows **Usage resets available** and **Use available reset…**
+when Codex reports an earned reset. Choose it and confirm to use one. If the count
+is unknown, choose **Check allowance now** first. Reset availability is separate
+from purchased workspace credits. Resets are never spent by automatic recovery.
+
+The equivalent terminal command is `relay account reset ACCOUNT --yes`. If a
+response is lost, use the same action again: Relay saves and reuses the pending
+request rather than submitting a new redemption. The menu calls this **Check
+previous reset…**. An optional `--request-id UUID` also identifies a specific
+logical attempt. Codex chooses the available reset; Relay checks the returned
+result and reads allowance again afterward.
+
+A reset only releases quota blocks when refreshed allowance permits it. Paused
+tasks, required reviews, and unrelated retry delays are retained. If the reset
+was used but allowance refresh failed, check allowance again; do not spend
+another reset to refresh the display.
+This uses the [documented Codex reset interface](https://learn.chatgpt.com/docs/app-server#8-earned-rate-limit-resets-chatgpt).
+
 ## Launch and recovery
 
 ```sh
@@ -109,6 +128,10 @@ allowance and does not fetch account allowance. `refresh` explicitly checks it.
 The menu uses one local status stream, a template icon, and native session actions.
 Opening it reads a fresh local snapshot, and visible rows update in place.
 Short-window and weekly allowance are labeled separately.
+Accounts assigned to live Relay sessions have a checkmark and an “In use” label;
+shared accounts also show their session count. To switch, open the Relay icon,
+then your session, then **Switch account**, and choose the account email. The
+current choice is marked **Current**. The menu tracks tasks started through Relay.
 Each session menu can switch to another enabled account after work and approvals
 finish. The worker checks allowance and session capacity before switching, then
 checks again that the session is idle before changing its login. Rejected actions

package/docs/publishing.md

@@ -8,8 +8,8 @@ Friends can run `npx relay-codex` or install it with `npm install -g relay-codex
 The GitHub repository is enough for friends to install or try Relay:
 
 ```sh
-npm install -g github:blackspider-ops/relay#v0.6.0
-npx --yes github:blackspider-ops/relay#v0.6.0 --version
+npm install -g github:blackspider-ops/relay#v0.7.0
+npx --yes github:blackspider-ops/relay#v0.7.0 --version
 ```
 
 `npx` runs packages; it is not a separate publishing service. Publishing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-codex",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Keep your Codex sessions moving between your own accounts.",
   "license": "MIT",
   "author": "blackspider-ops",

package/python/Menu.swift

@@ -186,6 +186,7 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
     func makeMenu() -> NSMenu {
         let sessions = current["sessions"] as? [[String: Any]] ?? []
         let accounts = current["accounts"] as? [[String: Any]] ?? []
+        let liveSessions = sessions.filter { $0["running"] as? Bool ?? true }
         let menu = NSMenu(); menu.delegate = self
         menu.autoenablesItems = false
         text("Relay · \(sessions.count) sessions", into: menu)
@@ -195,8 +196,12 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             if !actionRunning { action("Dismiss message", args: ["dismiss"], into: menu) }
         }
         if accounts.isEmpty { text("Add an account with relay setup in Terminal.", into: menu) }
+        if liveSessions.isEmpty && !accounts.isEmpty { text("No Relay sessions running. Start with relay run.", into: menu) }
         for account in accounts {
             let name = account["name"] as? String ?? "Account"
+            let accountID = account["id"] as? String ?? ""
+            let assigned = liveSessions.filter { $0["account"] as? String == accountID }
+            let inUse = assigned.isEmpty ? "" : assigned.count == 1 ? " · In use" : " · In use by \(assigned.count) sessions"
             let primary = account["primary"] as? [String: Any]
             let short = account["short_remaining"] as? String ?? (primary?["usedPercent"] as? NSNumber).map { "\(max(0, 100 - $0.intValue))%" } ?? "?"
             let remaining = short == "?" ? "allowance unknown" : short + " left"
@@ -206,6 +211,13 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             let submenu = NSMenu()
             submenu.autoenablesItems = false
             if let email = account["email"] as? String { text(email, into: submenu) }
+            if !assigned.isEmpty {
+                for session in assigned {
+                    let sessionName = session["name"] as? String ?? String((session["id"] as? String ?? "").prefix(10))
+                    text("In use by: \(sessionName)", into: submenu)
+                }
+                text("To switch: open that session → Switch account.", into: submenu)
+            }
             text("Short window: \(remaining)", into: submenu)
             if weekly != "?" { text("Weekly window: \(weekly) left", into: submenu) }
             for row in MenuController.accountTimingRows(account) {
@@ -215,12 +227,22 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             let lastChecked = MenuController.timestamp(account["usage_checked_at"]).map { date($0) } ?? "Not checked yet"
             text("Last checked: \(lastChecked)", into: submenu)
             if let id = account["id"] as? String {
+                submenu.addItem(.separator())
+                let pendingReset = account["reset_pending"] as? Bool ?? false
+                let resetCount = (account["reset_credits"] as? NSNumber)?.intValue
+                if let count = resetCount { text("Usage resets available: \(count)", into: submenu) }
+                else { text("Usage resets: check allowance to see availability.", into: submenu) }
+                if pendingReset || (resetCount ?? 0) > 0 {
+                    let reset = action(pendingReset ? "Check previous reset…" : "Use available reset…", args: ["confirm-reset", id, name, pendingReset ? "pending" : "new"], into: submenu)
+                    reset.isEnabled = !actionRunning && !(account["maintenance"] as? Bool ?? false)
+                }
                 submenu.addItem(.separator())
                 let enabled = account["enabled"] as? Bool ?? true
                 action(enabled ? "Disable for future routing" : "Enable for routing", args: ["account", enabled ? "disable" : "enable", id], into: submenu)
                 text("Current tasks keep running.", into: submenu)
             }
-            let entry = NSMenuItem(title: "\(name) · \(label)", action: nil, keyEquivalent: "")
+            let entry = NSMenuItem(title: "\(name)\(inUse) · \(label)", action: nil, keyEquivalent: "")
+            entry.state = assigned.isEmpty ? .off : .on
             entry.identifier = NSUserInterfaceItemIdentifier("account:" + (account["id"] as? String ?? name))
             entry.submenu = submenu; menu.addItem(entry)
         }
@@ -248,7 +270,7 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
                     let modelAllowed = models.isEmpty || model == nil || models.contains(model!)
                     let available = (account["enabled"] as? Bool ?? true) && !(account["maintenance"] as? Bool ?? false) && modelAllowed
                     let name = account["name"] as? String ?? accountID
-                    let choice = action(name + (available ? "" : " · unavailable"), args: ["switch", id, "--account", accountID, "--wait"], into: choices)
+                    let choice = action(name + (selected ? " · Current" : available ? "" : " · unavailable"), args: ["switch", id, "--account", accountID, "--wait"], into: choices)
                     choice.state = selected ? .on : .off
                     choice.isEnabled = !selected && available && !actionRunning
                 }
@@ -294,16 +316,29 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             guard alert.runModal() == .alertFirstButtonReturn else { return }
             args = ["retry", args[1], "--wait"]
         }
+        if args[0] == "confirm-reset" {
+            let pending = args[3] == "pending"
+            let alert = NSAlert(); alert.messageText = pending ? "Check the previous reset?" : "Use one usage reset?"
+            alert.informativeText = args[2] + "\n\n" + (pending ? "Relay will check the same pending request. If it already used a reset, another one will not be spent." : "This spends one earned reset on eligible usage limits for this account. Allowance will be checked afterward. Paused tasks and review holds stay paused.")
+            alert.addButton(withTitle: pending ? "Check reset" : "Use reset"); alert.addButton(withTitle: "Cancel")
+            NSApp.activate(ignoringOtherApps: true)
+            guard alert.runModal() == .alertFirstButtonReturn else { return }
+            args = ["account", "reset", args[1], "--yes", "--request-id", UUID().uuidString]
+        }
         actionRunning = true; actionFailed = false; actionNotice = "Applying change…"; render()
-        let proc = process(args); let pipe = Pipe(); proc.standardOutput = FileHandle.nullDevice; proc.standardError = pipe
+        let isReset = Array(args.prefix(2)) == ["account", "reset"]
+        let proc = process(args); let pipe = Pipe()
+        if isReset { proc.standardOutput = pipe } else { proc.standardOutput = FileHandle.nullDevice }
+        proc.standardError = pipe
         DispatchQueue.global(qos: .utility).async { [weak self] in
             do {
                 try proc.run(); let bytes = pipe.fileHandleForReading.readDataToEndOfFile(); proc.waitUntilExit()
                 let failed = proc.terminationStatus != 0
                 let detail = String(data: bytes, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                let resetResult = detail.split(separator: "\n").last.map(String.init) ?? "Reset check finished. Check the account's allowance."
                 DispatchQueue.main.async {
                     self?.actionRunning = false; self?.actionFailed = failed
-                    self?.actionNotice = failed ? (detail.isEmpty ? "Action failed. Check relay events." : detail) : MenuController.successMessage(args)
+                    self?.actionNotice = failed ? (detail.isEmpty ? "Action failed. Check relay events." : detail) : isReset ? resetResult : MenuController.successMessage(args)
                     self?.render(); self?.refreshSnapshot()
                 }
             } catch { DispatchQueue.main.async { self?.actionRunning = false; self?.actionFailed = true; self?.actionNotice = "Could not run that action."; self?.render() } }
@@ -363,6 +398,27 @@ if CommandLine.arguments.contains("--self-check") {
     let switchArgs = ["switch", "live", "--account", "two", "--wait"]
     let correctChoices = findAction(switchArgs, in: controls)?.isEnabled == true && findAction(["switch", "live", "--account", "one", "--wait"], in: controls)?.state == .on && findAction(["switch", "live", "--account", "off", "--wait"], in: controls)?.isEnabled == false
     let stoppedControls = findAction(["restart", "stopped", "--if-stopped"], in: controls) != nil && findAction(["pause", "stopped", "--wait"], in: controls) == nil
+    let activeMarker = controls.items.first { $0.identifier?.rawValue == "account:one" }
+    let currentChoice = findAction(["switch", "live", "--account", "one", "--wait"], in: controls)
+    let correctMarker = activeMarker?.state == .on && activeMarker?.title.contains("In use") == true && currentChoice?.title.contains("Current") == true
+    let originalSessions = controller.current["sessions"]
+    controller.current["sessions"] = [["id": "a", "account": "one", "running": true], ["id": "b", "account": "one", "running": true], ["id": "c", "account": "two", "running": true], ["id": "d", "account": "off", "running": false]]
+    let multiple = controller.makeMenu()
+    let one = multiple.items.first { $0.identifier?.rawValue == "account:one" }
+    let two = multiple.items.first { $0.identifier?.rawValue == "account:two" }
+    let off = multiple.items.first { $0.identifier?.rawValue == "account:off" }
+    let correctMultiple = one?.title.contains("In use by 2 sessions") == true && two?.state == .on && off?.state == .off
+    controller.current["sessions"] = [["id": "stopped", "account": "one", "running": false]]
+    let empty = controller.makeMenu()
+    let correctEmpty = empty.items.contains { $0.title.contains("No Relay sessions running") } && empty.items.first { $0.identifier?.rawValue == "account:one" }?.state == .off
+    controller.current["sessions"] = originalSessions
+    let originalAccounts = controller.current["accounts"]
+    controller.current["accounts"] = [["id": "one", "name": "One", "reset_credits": 2], ["id": "two", "name": "Two", "reset_credits": 0], ["id": "unknown", "name": "Unknown"], ["id": "pending", "name": "Pending", "reset_pending": true]]
+    let resets = controller.makeMenu()
+    let correctResets = findAction(["confirm-reset", "one", "One", "new"], in: resets)?.isEnabled == true && findAction(["confirm-reset", "two", "Two", "new"], in: resets) == nil && findAction(["confirm-reset", "unknown", "Unknown", "new"], in: resets) == nil && findAction(["confirm-reset", "pending", "Pending", "pending"], in: resets) != nil
+    controller.actionRunning = true
+    let resetLocked = findAction(["confirm-reset", "one", "One", "new"], in: controller.makeMenu())?.isEnabled == false
+    controller.current["accounts"] = originalAccounts
     controller.actionRunning = true; controller.actionNotice = "Applying change…"
     let pending = controller.makeMenu()
     let correctPending = findAction(switchArgs, in: pending)?.isEnabled == false && findAction(["refresh"], in: pending)?.isEnabled == false && findAction(["copy", "relay attach live"], in: pending)?.isEnabled == true
@@ -371,7 +427,9 @@ if CommandLine.arguments.contains("--self-check") {
     let retainedResult = controller.makeMenu().items.contains { $0.title == "Task is busy." }
     print("Account choices and stopped controls correct: \(correctChoices && stoppedControls)")
     print("Pending action protected and result retained: \(correctPending && retainedResult)")
-    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming && correctChoices && stoppedControls && correctPending && retainedResult ? 0 : 1)
+    print("In-use accounts and current choice marked: \(correctMarker && correctMultiple && correctEmpty)")
+    print("Available and pending reset actions protected: \(correctResets && resetLocked)")
+    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming && correctChoices && stoppedControls && correctPending && retainedResult && correctMarker && correctMultiple && correctEmpty && correctResets && resetLocked ? 0 : 1)
 } else {
     let app = NSApplication.shared
     let delegate = MenuController(); app.delegate = delegate; app.run()

package/python/commands.py

@@ -77,6 +77,7 @@ def remaining_percent(window):
 
 def snapshot(state, include_inactive=False):
     from router import labels, VERSION
+    import resets
 
     pool = Pool(state)
     try:
@@ -111,6 +112,8 @@ def snapshot(state, include_inactive=False):
                     "weekly_remaining": remaining_percent(windows.get("secondary")),
                     "usage_known": usage is not None,
                     "usage_checked_at": pool.checked_at(label),
+                    "reset_credits": resets.available(usage),
+                    "reset_pending": resets.pending(state / "accounts" / label),
                     "maintenance": options.get("maintenance", False),
                     "next_check": min(
                         (b["next_check"] for b in blocks if b["account"] == label),
@@ -313,6 +316,16 @@ async def _manage(args, state, binary):
     pool = Pool(state)
     try:
         label = resolve_label(state, args.label) if args.action != "add" else args.label
+        if args.action == "reset":
+            import resets
+
+            if not args.yes:
+                raise RouterError(
+                    "This uses one earned usage reset for this account. Add --yes to confirm, or use the menu's Use available reset action."
+                )
+            result = await resets.consume(state, label, binary, args.request_id)
+            print(resets.message(result))
+            return 0
         if args.action in {"enable", "disable", "priority", "cap", "rename", "models"}:
             if args.action in {"enable", "disable"}:
                 pool.set_options(label, enabled=args.action == "enable")
@@ -648,6 +661,7 @@ def add_parsers(sub):
         "priority",
         "cap",
         "models",
+        "reset",
     ]:
         p = child.add_parser(action)
         p.add_argument("label")
@@ -661,6 +675,16 @@ def add_parsers(sub):
             p.add_argument("value", type=int)
         if action == "models":
             p.add_argument("values", nargs="*")
+        if action == "reset":
+            p.add_argument(
+                "--yes",
+                action="store_true",
+                help="Confirm using one earned usage reset",
+            )
+            p.add_argument(
+                "--request-id",
+                help="Optional UUID; reuse it to check the same redemption attempt",
+            )
     config = sub.add_parser("config", help="Set global or named recovery profiles")
     config.add_argument("key", nargs="?")
     config.add_argument("value", nargs="?")

package/python/resets.py

@@ -0,0 +1,201 @@
+"""Explicit earned-reset redemption. Never called by automatic recovery."""
+
+import hashlib
+import json
+import time
+import uuid
+
+from pool import Pool, blocked, reset_time
+from settings import atomic_json
+
+OUTCOMES = {"reset", "alreadyRedeemed", "nothingToReset", "noCredit"}
+
+
+def available(snapshot):
+    summary = (snapshot or {}).get("rateLimitResetCredits")
+    count = summary.get("availableCount") if isinstance(summary, dict) else None
+    return count if type(count) is int and count >= 0 else None
+
+
+def identity(home):
+    marker = (home / "enrolled").read_bytes()
+    return json.loads(marker).get("identity") or hashlib.sha256(marker).hexdigest()
+
+
+def receipt(home):
+    path = home / "reset-attempt.json"
+    if not path.exists():
+        return {}
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(
+            "Unreadable reset receipt. Check this account before trying again."
+        )
+    return value
+
+
+def pending(home):
+    try:
+        value = receipt(home)
+        return value.get("state") == "pending" and value.get("identity") == identity(
+            home
+        )
+    except (OSError, ValueError):
+        return False
+
+
+def update_allowance(pool, label, snapshot):
+    """Only verified allowance can lift a quota block. Keep other retry reasons."""
+    if not isinstance(snapshot, dict) or not (
+        isinstance(snapshot.get("rateLimits"), dict)
+        or isinstance(snapshot.get("rateLimitsByLimitId"), dict)
+        or type(snapshot.get("ordinaryUsageAllowed")) is bool
+    ):
+        raise ValueError(
+            "Codex returned unrecognized allowance data; quota blocks were retained."
+        )
+    pool.save(label, snapshot)
+    with pool.db() as db:
+        scopes = [
+            r[0]
+            for r in db.execute(
+                "SELECT scope FROM blocks WHERE label=? AND reason='quota'", (label,)
+            )
+        ]
+        for scope in scopes:
+            model = None if scope == "*" else scope
+            if blocked(snapshot, model):
+                until = reset_time(snapshot, model) or time.time() + 300
+                db.execute(
+                    "UPDATE blocks SET until=? WHERE label=? AND scope=? AND reason='quota'",
+                    (until, label, scope),
+                )
+            else:
+                db.execute(
+                    "DELETE FROM blocks WHERE label=? AND scope=? AND reason='quota'",
+                    (label, scope),
+                )
+    pool.signal()
+
+
+async def consume(state, label, binary, request_id=None):
+    from router import Account, RouterError, RemoteError, account_home, labels
+
+    if label not in labels(state):
+        raise RouterError("Choose an enrolled account from relay list.")
+    if request_id is not None:
+        try:
+            request_id = str(uuid.UUID(request_id))
+        except (ValueError, AttributeError):
+            raise RouterError("Use a UUID for --request-id.") from None
+    home = account_home(state, label)
+    pool = Pool(state)
+    account = Account(label, home, binary, pool)
+    try:
+        # The same per-account credential lock is used by old and new brokers.
+        # A reset does not require replacing the coordinator or a task's login.
+        async with account.operation() as rpc:
+            signed_in = identity(home)
+            previous = receipt(home)
+            same_identity = previous.get("identity") == signed_in
+            retry = same_identity and previous.get("state") == "pending"
+            known = (
+                same_identity
+                and request_id is not None
+                and previous.get("request_id") == request_id
+                and previous.get("state") == "done"
+            )
+            key = (
+                previous.get("request_id") if retry else request_id or str(uuid.uuid4())
+            )
+            if retry:
+                try:
+                    key = str(uuid.UUID(key))
+                except (ValueError, AttributeError, TypeError):
+                    raise RouterError(
+                        "The pending reset receipt is unreadable. Check account usage before trying again."
+                    ) from None
+            outcome = previous.get("outcome") if known else None
+            if known and (not isinstance(outcome, str) or outcome not in OUTCOMES):
+                raise RouterError(
+                    "The saved reset result is unreadable. Check account usage before trying again."
+                )
+            if known and outcome == "reset":
+                outcome = "alreadyRedeemed"
+            if not retry and not known:
+                current = await rpc.call("account/rateLimits/read")
+                update_allowance(pool, label, current)
+                count = available(current)
+                if count == 0:
+                    return {"outcome": "noCredit", "refreshed": True}
+                if count is None:
+                    raise RouterError(
+                        "Codex did not report reset availability. Check allowance again before using a reset."
+                    )
+            if not known:
+                attempt = {
+                    "request_id": key,
+                    "identity": signed_in,
+                    "state": "pending",
+                    "at": time.time(),
+                }
+                atomic_json(home / "reset-attempt.json", attempt)
+                pool.invalidate(label)
+                pool.signal()
+                try:
+                    response = await rpc.call(
+                        "account/rateLimitResetCredit/consume", {"idempotencyKey": key}
+                    )
+                    outcome = response.get("outcome")
+                except RemoteError as error:
+                    if error.payload.get("code") in {-32601, -32602}:
+                        atomic_json(
+                            home / "reset-attempt.json",
+                            {**attempt, "state": "rejected"},
+                        )
+                        raise RouterError(
+                            "This Codex runtime cannot use resets through Relay. Update Codex and try again."
+                        ) from None
+                    raise RouterError(
+                        "Reset result could not be confirmed. Try this action again; Relay will reuse the same pending request."
+                    ) from None
+                except Exception:
+                    raise RouterError(
+                        "Reset result could not be confirmed. Try this action again; Relay will reuse the same pending request."
+                    ) from None
+                if not isinstance(outcome, str) or outcome not in OUTCOMES:
+                    raise RouterError(
+                        "Reset result was not recognized. Try again to check the same pending request."
+                    )
+                atomic_json(
+                    home / "reset-attempt.json",
+                    {**attempt, "state": "done", "outcome": outcome},
+                )
+            refreshed = False
+            try:
+                snapshot = await rpc.call("account/rateLimits/read")
+                update_allowance(pool, label, snapshot)
+                refreshed = True
+            except Exception:
+                pool.invalidate(label)
+                pool.signal()
+            pool.record(
+                "reset_checked", account=label, outcome=outcome, refreshed=refreshed
+            )
+            return {"outcome": outcome, "refreshed": refreshed}
+    finally:
+        pool.close()
+
+
+def message(result):
+    text = {
+        "reset": "Used one usage reset.",
+        "alreadyRedeemed": "The previous reset was already used; no additional reset was spent.",
+        "nothingToReset": "No usage window is eligible for a reset; no reset was used.",
+        "noCredit": "No usage resets are available; no reset was used.",
+    }[result["outcome"]]
+    return text + (
+        " Allowance updated."
+        if result["refreshed"]
+        else " Allowance could not be refreshed; choose Check allowance now."
+    )

package/python/router.py

@@ -24,7 +24,7 @@ from pool import Pool, blocked, reset_time, failure_kind, file_lock
 from launch import translate, RESUME_FIELDS
 import settings
 
-VERSION = "0.6.0"
+VERSION = "0.7.0"
 _support = Path.home() / "Library/Application Support"
 _legacy = _support / "Codex Accounts"
 _default_state = _legacy if (_legacy / "accounts").exists() else _support / "Relay"
@@ -2274,7 +2274,7 @@ def selected_binary(args, state):
         return None
     if (
         args.command == "account"
-        and args.action not in {"add", "reauth"}
+        and args.action not in {"add", "reauth", "reset"}
         and not getattr(args, "revoke", False)
     ):
         return None

package/tests/fake_native.py

@@ -126,12 +126,32 @@ for raw in sys.stdin:
         elif method == "account/login/start":
             result = {"type": params["type"]}
         elif method == "account/rateLimits/read":
+            reset_count = change(lambda d: d.get("reset_credit_count", 1))
             result = {
                 "ordinaryUsageAllowed": True,
                 "rateLimits": {
                     "primary": {"usedPercent": 20, "resetsAt": int(time.time()) + 3600}
                 },
+                "rateLimitResetCredits": {
+                    "availableCount": reset_count,
+                    "credits": None,
+                },
             }
+        elif method == "account/rateLimitResetCredit/consume":
+
+            def redeem(data):
+                keys = data.setdefault("reset_keys", [])
+                key = params["idempotencyKey"]
+                if key in keys:
+                    return {"outcome": "alreadyRedeemed"}
+                count = data.get("reset_credit_count", 1)
+                if count <= 0:
+                    return {"outcome": "noCredit"}
+                keys.append(key)
+                data["reset_credit_count"] = count - 1
+                return {"outcome": "reset"}
+
+            result = change(redeem)
         elif method in ("thread/start", "thread/fork"):
             thread = str(uuid.uuid4())
             value = {

package/tests/test_resets.py

@@ -0,0 +1,227 @@
+"""Earned-reset tests use synthetic accounts and never redeem a real credit."""
+
+import asyncio
+import json
+from pathlib import Path
+import tempfile
+import time
+import unittest
+import uuid
+from unittest.mock import patch
+
+import commands
+from pool import Pool
+from router import Account, RouterError, RemoteError, parse_arguments
+from settings import atomic_json
+import resets
+
+
+class ResetService:
+    def __init__(self):
+        self.count = 2
+        self.blocked = True
+        self.calls = []
+        self.completed = set()
+        self.lose_reply = False
+        self.fail_refresh = False
+        self.residual_limit = False
+        self.outcome = None
+        self.reject = False
+
+    async def call(self, method, params=None):
+        await asyncio.sleep(0)
+        if method == "account/rateLimits/read":
+            if self.fail_refresh and self.completed:
+                raise asyncio.TimeoutError()
+            return {
+                "ordinaryUsageAllowed": not self.blocked,
+                "rateLimits": {
+                    "primary": {
+                        "usedPercent": 100 if self.blocked else 0,
+                        "resetsAt": time.time() + 3600,
+                    }
+                },
+                "rateLimitResetCredits": {
+                    "availableCount": self.count,
+                    "credits": None,
+                },
+            }
+        if method != "account/rateLimitResetCredit/consume":
+            raise AssertionError(method)
+        if self.reject:
+            raise RemoteError({"code": -32601})
+        key = params["idempotencyKey"]
+        self.calls.append(key)
+        if key in self.completed:
+            return {"outcome": "alreadyRedeemed"}
+        if self.outcome in {"noCredit", "nothingToReset"}:
+            if self.outcome == "noCredit":
+                self.count = 0
+            return {"outcome": self.outcome}
+        self.completed.add(key)
+        self.count -= 1
+        self.blocked = self.residual_limit
+        if self.lose_reply:
+            self.lose_reply = False
+            raise asyncio.TimeoutError()
+        return {"outcome": self.outcome or "reset"}
+
+
+class ResetTests(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.tmp = tempfile.TemporaryDirectory(prefix="relay-reset-test-")
+        self.root = Path(self.tmp.name)
+        self.home = self.root / "accounts" / "one"
+        self.home.mkdir(parents=True)
+        atomic_json(self.home / "enrolled", {"identity": "fake-account-A"})
+        self.pool = Pool(self.root)
+        self.service = ResetService()
+        service = self.service
+
+        class TestAccount(Account):
+            async def start(self):
+                self.rpc = service
+
+            async def close(self):
+                self.rpc = None
+
+        self.patch = patch("router.Account", TestAccount)
+        self.patch.start()
+
+    async def asyncTearDown(self):
+        self.patch.stop()
+        self.pool.close()
+        self.tmp.cleanup()
+
+    async def test_success_refreshes_allowance_and_only_lifts_verified_quota_blocks(
+        self,
+    ):
+        self.pool.mark("one", reason="quota")
+        self.pool.mark("one", "other-model", reason="auth")
+        self.pool.intent("thread", {"review_required": True})
+        self.pool.touch(paused=True)
+        result = await resets.consume(self.root, "one", "fake")
+        self.assertEqual(result, {"outcome": "reset", "refreshed": True})
+        self.assertEqual(resets.available(self.pool.cached("one")), 1)
+        with self.pool.db() as db:
+            self.assertEqual(
+                db.execute("SELECT scope,reason FROM blocks").fetchall(),
+                [("other-model", "auth")],
+            )
+            details = json.loads(
+                db.execute(
+                    "SELECT details FROM session_details WHERE id=?",
+                    (self.pool.session,),
+                ).fetchone()[0]
+            )
+        self.assertTrue(details["paused"])
+        self.assertTrue(self.pool.intent("thread")["review_required"])
+        self.assertEqual(
+            (self.home / "reset-attempt.json").stat().st_mode & 0o777, 0o600
+        )
+
+    async def test_lost_reply_reuses_pending_key_even_if_next_click_has_a_new_key(self):
+        self.service.lose_reply = True
+        with self.assertRaisesRegex(RouterError, "same pending request"):
+            await resets.consume(self.root, "one", "fake", str(uuid.uuid4()))
+        self.assertTrue(resets.pending(self.home))
+        account = commands.snapshot(self.root)["accounts"][0]
+        self.assertTrue(account["reset_pending"])
+        self.assertIsNone(account["reset_credits"])
+        result = await resets.consume(self.root, "one", "fake", str(uuid.uuid4()))
+        self.assertEqual(result["outcome"], "alreadyRedeemed")
+        self.assertEqual(len(set(self.service.calls)), 1)
+        self.assertEqual(self.service.count, 1)
+        self.assertFalse(resets.pending(self.home))
+
+    async def test_concurrent_duplicate_request_is_redeemed_once(self):
+        key = str(uuid.uuid4())
+        results = await asyncio.gather(
+            *(resets.consume(self.root, "one", "fake", key) for _ in range(2))
+        )
+        self.assertEqual({r["outcome"] for r in results}, {"reset", "alreadyRedeemed"})
+        self.assertEqual(self.service.calls, [key])
+
+    async def test_success_with_failed_refresh_does_not_claim_updated_limits(self):
+        self.service.fail_refresh = True
+        key = str(uuid.uuid4())
+        self.pool.mark("one", reason="quota")
+        result = await resets.consume(self.root, "one", "fake", key)
+        self.assertFalse(result["refreshed"])
+        self.assertIn("could not be refreshed", resets.message(result))
+        self.assertIsNone(self.pool.cached("one"))
+        self.assertGreater(self.pool.deadline("one"), time.time())
+        retry = await resets.consume(self.root, "one", "fake", key)
+        self.assertEqual(retry["outcome"], "alreadyRedeemed")
+        self.assertEqual(len(self.service.calls), 1)
+
+    async def test_remaining_limit_is_retained_after_a_reset(self):
+        self.service.residual_limit = True
+        self.pool.mark("one", reason="quota")
+        await resets.consume(self.root, "one", "fake")
+        self.assertGreater(self.pool.deadline("one"), time.time())
+
+    async def test_no_credit_or_nothing_to_reset_are_reported_without_success_claim(
+        self,
+    ):
+        for outcome in ("noCredit", "nothingToReset"):
+            self.service.outcome = outcome
+            self.service.count = 2
+            result = await resets.consume(self.root, "one", "fake")
+            self.assertEqual(result["outcome"], outcome)
+            self.assertIn("no reset was used", resets.message(result))
+        self.service.count = 0
+        self.service.calls.clear()
+        result = await resets.consume(self.root, "one", "fake")
+        self.assertEqual(result["outcome"], "noCredit")
+        self.assertFalse(self.service.calls)
+
+    async def test_unknown_outcome_remains_pending_and_unsupported_method_is_actionable(
+        self,
+    ):
+        self.service.outcome = "newUnknownOutcome"
+        with self.assertRaisesRegex(RouterError, "not recognized"):
+            await resets.consume(self.root, "one", "fake")
+        self.assertTrue(resets.pending(self.home))
+        self.service.reject = True
+        with self.assertRaisesRegex(RouterError, "Update Codex"):
+            await resets.consume(self.root, "one", "fake")
+        self.assertFalse(resets.pending(self.home))
+
+    async def test_cli_requires_confirmation_before_starting_redemption(self):
+        args = parse_arguments(["account", "reset", "one"])
+        with patch("resets.consume", side_effect=AssertionError("Unconfirmed reset")):
+            with self.assertRaisesRegex(RouterError, "--yes"):
+                await commands.manage(args, self.root, "fake")
+
+    async def test_real_jsonl_helper_redeems_and_refreshes_synthetic_account(self):
+        from test_services import fake_executable
+
+        self.patch.stop()
+        binary = fake_executable(self.root)
+        result = await resets.consume(self.root, "one", binary)
+        self.assertEqual(result, {"outcome": "reset", "refreshed": True})
+        history = json.loads((self.home / "fake-history.json").read_text())
+        self.assertEqual(len(history["reset_keys"]), 1)
+        self.assertEqual(history["reset_credit_count"], 0)
+        self.assertEqual(
+            sum(c["method"] == "account/rateLimits/read" for c in history["calls"]), 2
+        )
+
+    def test_available_count_is_authoritative_and_invalid_values_stay_unknown(self):
+        self.assertEqual(
+            resets.available(
+                {"rateLimitResetCredits": {"availableCount": 3, "credits": []}}
+            ),
+            3,
+        )
+        for count in (-1, True, "2", 1.5, None):
+            self.assertIsNone(
+                resets.available({"rateLimitResetCredits": {"availableCount": count}})
+            )
+        with self.assertRaises(ValueError):
+            resets.update_allowance(self.pool, "one", {})
+
+
+if __name__ == "__main__":
+    unittest.main()