relay-codex 0.6.1 → 0.7.1

package/README.md

@@ -68,6 +68,10 @@ 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. The button
+is enabled only with weekly allowance at 0% and its reset more than 48 hours away. 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,28 @@ 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. It is enabled only when weekly allowance is
+fully exhausted (0%) and the weekly reset is **more than 48 hours away**. Exactly
+48 hours, any weekly allowance left, or unknown weekly data keeps it disabled.
+The reason appears below the button. 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. Pending retries must satisfy
+the same weekly rule; their saved request is retained when locked. 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

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.1
-npx --yes github:blackspider-ops/relay#v0.6.1 --version
+npm install -g github:blackspider-ops/relay#v0.7.1
+npx --yes github:blackspider-ops/relay#v0.7.1 --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.1",
+  "version": "0.7.1",
   "description": "Keep your Codex sessions moving between your own accounts.",
   "license": "MIT",
   "author": "blackspider-ops",

package/python/Menu.swift

@@ -12,6 +12,8 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
     var reconnect: DispatchWorkItem?
     var stopping = false
     var snapshotInFlight = false
+    var resetExpiry: DispatchWorkItem?
+    var menuOpen = false
     let command = Bundle.main.object(forInfoDictionaryKey: "RelayCommand") as? String ?? "/usr/bin/false"
     let state = Bundle.main.object(forInfoDictionaryKey: "RelayState") as? String ?? ""
 
@@ -140,6 +142,15 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
         guard let seconds = value as? Double, seconds.isFinite, seconds > 0 else { return nil }
         return seconds
     }
+    static func resetBlockReason(_ account: [String: Any], now: Double = Date().timeIntervalSince1970) -> String? {
+        guard let weekly = account["secondary"] as? [String: Any], let used = (weekly["usedPercent"] as? NSNumber)?.doubleValue, used.isFinite else {
+            return "Reset locked: check allowance to confirm the weekly limit and reset time."
+        }
+        guard used >= 100 else { return "Reset locked: weekly allowance must be fully exhausted (0%)." }
+        guard let at = timestamp(weekly["resetsAt"]) else { return "Reset locked: check allowance to confirm the weekly limit and reset time." }
+        guard at - now > 48 * 60 * 60 else { return "Reset locked: the weekly reset must be more than 48 hours away." }
+        return nil
+    }
     static func accountTimingRows(_ account: [String: Any]) -> [TimingRow] {
         var rows: [TimingRow] = []
         if let primary = account["primary"] as? [String: Any], let at = timestamp(primary["resetsAt"]) {
@@ -182,6 +193,7 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
         updateTimes(menu)
         if let visible = item.menu { MenuController.synchronise(visible, with: menu) }
         else { item.menu = menu }
+        if menuOpen { scheduleResetExpiry() }
     }
     func makeMenu() -> NSMenu {
         let sessions = current["sessions"] as? [[String: Any]] ?? []
@@ -227,6 +239,17 @@ 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 blocked = MenuController.resetBlockReason(account)
+                    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) && blocked == nil
+                    if let blocked = blocked { text(blocked, into: submenu) }
+                }
                 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)
@@ -289,12 +312,37 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
         return menu
     }
     func menuWillOpen(_ menu: NSMenu) {
+        menuOpen = true
+        render()
         refreshSnapshot()
         updateTimes(menu)
         for entry in menu.items where entry.title == "Open at login" {
             entry.state = FileManager.default.fileExists(atPath: NSHomeDirectory() + "/Library/LaunchAgents/local.relay.menu.plist") ? .on : .off
         }
     }
+    func scheduleResetExpiry() {
+        resetExpiry?.cancel()
+        let now = Date().timeIntervalSince1970
+        let accounts = current["accounts"] as? [[String: Any]] ?? []
+        let boundaries = accounts.compactMap { account -> Double? in
+            guard MenuController.resetBlockReason(account, now: now) == nil, let weekly = account["secondary"] as? [String: Any], let at = MenuController.timestamp(weekly["resetsAt"]) else { return nil }
+            return at - 48 * 60 * 60
+        }
+        if let boundary = boundaries.min() {
+            let expiry = DispatchWorkItem { [weak self] in self?.render() }
+            resetExpiry = expiry
+            DispatchQueue.main.asyncAfter(deadline: .now() + max(0, boundary - now), execute: expiry)
+        }
+    }
+    func menuDidClose(_ menu: NSMenu) { menuOpen = false; resetExpiry?.cancel(); resetExpiry = nil }
+    func resetAllowed(_ id: String) -> Bool {
+        let accounts = current["accounts"] as? [[String: Any]] ?? []
+        guard let account = accounts.first(where: { $0["id"] as? String == id }) else {
+            actionNotice = "Reset locked: account details are unavailable."; actionFailed = true; render(); return false
+        }
+        if let reason = MenuController.resetBlockReason(account) { actionNotice = reason; actionFailed = true; render(); return false }
+        return true
+    }
     @objc func runAction(_ sender: NSMenuItem) {
         guard var args = sender.representedObject as? [String], !args.isEmpty else { return }
         if args[0] == "copy" { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(args[1], forType: .string); return }
@@ -307,16 +355,31 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             guard alert.runModal() == .alertFirstButtonReturn else { return }
             args = ["retry", args[1], "--wait"]
         }
+        if args[0] == "confirm-reset" {
+            guard resetAllowed(args[1]) else { return }
+            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 }
+            guard resetAllowed(args[1]) 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() } }
@@ -390,6 +453,20 @@ if CommandLine.arguments.contains("--self-check") {
     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, "secondary": ["usedPercent": 100, "resetsAt": Date().timeIntervalSince1970 + 72 * 3600]], ["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
+    let policyNow = 2000000000.0
+    let far: [String: Any] = ["secondary": ["usedPercent": 100, "resetsAt": policyNow + 172801]]
+    let exact: [String: Any] = ["secondary": ["usedPercent": 100, "resetsAt": policyNow + 172800]]
+    let near: [String: Any] = ["secondary": ["usedPercent": 100, "resetsAt": policyNow + 172799]]
+    let left: [String: Any] = ["secondary": ["usedPercent": 99.99, "resetsAt": policyNow + 259200]]
+    let correctPolicy = MenuController.resetBlockReason(far, now: policyNow) == nil && MenuController.resetBlockReason(exact, now: policyNow) != nil && MenuController.resetBlockReason(near, now: policyNow) != nil && MenuController.resetBlockReason(left, now: policyNow) != nil && MenuController.resetBlockReason([:], now: policyNow) != nil
+    let pendingLocked = findAction(["confirm-reset", "pending", "Pending", "pending"], in: resets)?.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
@@ -399,7 +476,9 @@ if CommandLine.arguments.contains("--self-check") {
     print("Account choices and stopped controls correct: \(correctChoices && stoppedControls)")
     print("Pending action protected and result retained: \(correctPending && retainedResult)")
     print("In-use accounts and current choice marked: \(correctMarker && correctMultiple && correctEmpty)")
-    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming && correctChoices && stoppedControls && correctPending && retainedResult && correctMarker && correctMultiple && correctEmpty ? 0 : 1)
+    print("Available and pending reset actions protected: \(correctResets && resetLocked)")
+    print("Weekly zero and more-than-48-hour guard enforced: \(correctPolicy && pendingLocked)")
+    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming && correctChoices && stoppedControls && correctPending && retainedResult && correctMarker && correctMultiple && correctEmpty && correctResets && resetLocked && correctPolicy && pendingLocked ? 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,9 @@ 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),
+                    "reset_lock_reason": resets.weekly_block_reason(usage),
                     "maintenance": options.get("maintenance", False),
                     "next_check": min(
                         (b["next_check"] for b in blocks if b["account"] == label),
@@ -313,6 +317,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 +662,7 @@ def add_parsers(sub):
         "priority",
         "cap",
         "models",
+        "reset",
     ]:
         p = child.add_parser(action)
         p.add_argument("label")
@@ -661,6 +676,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,228 @@
+"""Explicit earned-reset redemption. Never called by automatic recovery."""
+
+import hashlib
+import json
+import math
+import time
+import uuid
+
+from pool import Pool, blocked, reset_time
+from settings import atomic_json
+
+OUTCOMES = {"reset", "alreadyRedeemed", "nothingToReset", "noCredit"}
+WEEKLY_RESET_BUFFER = 48 * 60 * 60
+
+
+def weekly_block_reason(snapshot, now=None):
+    window = ((snapshot or {}).get("rateLimits") or {}).get("secondary")
+    if not isinstance(window, dict):
+        return (
+            "Reset locked: check allowance to confirm the weekly limit and reset time."
+        )
+    used, at = window.get("usedPercent"), window.get("resetsAt")
+    if type(used) not in (int, float) or not math.isfinite(used):
+        return (
+            "Reset locked: check allowance to confirm the weekly limit and reset time."
+        )
+    if used < 100:
+        return "Reset locked: weekly allowance must be fully exhausted (0%)."
+    if type(at) not in (int, float) or not math.isfinite(at):
+        return (
+            "Reset locked: check allowance to confirm the weekly limit and reset time."
+        )
+    if at - (time.time() if now is None else now) <= WEEKLY_RESET_BUFFER:
+        return "Reset locked: the weekly reset must be more than 48 hours away."
+    return None
+
+
+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 known:
+                current = await rpc.call("account/rateLimits/read")
+                update_allowance(pool, label, current)
+                reason = weekly_block_reason(current)
+                if reason:
+                    raise RouterError(reason)
+                count = available(current)
+                if count == 0 and not retry:
+                    return {"outcome": "noCredit", "refreshed": True}
+                if count is None and not retry:
+                    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.1"
+VERSION = "0.7.1"
 _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,45 @@ 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))
+            weekly = change(
+                lambda d: (
+                    {
+                        "usedPercent": d["reset_weekly_used"],
+                        "resetsAt": d["reset_weekly_at"],
+                    }
+                    if "reset_weekly_used" in d
+                    else None
+                )
+            )
             result = {
                 "ordinaryUsageAllowed": True,
                 "rateLimits": {
-                    "primary": {"usedPercent": 20, "resetsAt": int(time.time()) + 3600}
+                    "primary": {"usedPercent": 20, "resetsAt": int(time.time()) + 3600},
+                    "secondary": weekly,
+                },
+                "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
+                if "reset_weekly_used" in data:
+                    data["reset_weekly_used"] = 0
+                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,289 @@
+"""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
+        self.weekly_used = 100
+        self.weekly_at = time.time() + 72 * 3600
+
+    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,
+                    },
+                    "secondary": {
+                        "usedPercent": self.weekly_used,
+                        "resetsAt": self.weekly_at,
+                    },
+                },
+                "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_weekly_guard_blocks_all_mutation_until_zero_and_more_than_48_hours(
+        self,
+    ):
+        for used, hours in ((0, 72), (99.99, 72), (100, 48), (100, 47), (100, -1)):
+            with self.subTest(used=used, hours=hours):
+                self.service.weekly_used = used
+                self.service.weekly_at = time.time() + hours * 3600
+                with self.assertRaisesRegex(RouterError, "Reset locked"):
+                    await resets.consume(self.root, "one", "fake")
+                self.assertFalse(self.service.calls)
+                self.assertFalse((self.home / "reset-attempt.json").exists())
+        self.service.weekly_used = 100
+        self.service.weekly_at = time.time() + 72 * 3600
+        result = await resets.consume(self.root, "one", "fake")
+        self.assertEqual(result["outcome"], "reset")
+
+    async def test_pending_retry_cannot_bypass_a_changed_weekly_guard(self):
+        self.service.lose_reply = True
+        with self.assertRaises(RouterError):
+            await resets.consume(self.root, "one", "fake")
+        self.service.weekly_used = 0
+        with self.assertRaisesRegex(RouterError, "fully exhausted"):
+            await resets.consume(self.root, "one", "fake")
+        self.assertEqual(len(self.service.calls), 1)
+        self.assertTrue(resets.pending(self.home))
+        self.assertEqual(self.service.count, 1)
+
+    def test_weekly_guard_exact_boundary_unknown_values_and_unrounded_allowance(self):
+        now = 2000000000
+
+        def usage(used, at):
+            return {"rateLimits": {"secondary": {"usedPercent": used, "resetsAt": at}}}
+
+        self.assertIsNone(resets.weekly_block_reason(usage(100, now + 172801), now))
+        for used, at in (
+            (100, now + 172800),
+            (100, now + 172799),
+            (99.999, now + 200000),
+            (100, None),
+            (None, now + 200000),
+            (float("nan"), now + 200000),
+            (100, float("inf")),
+        ):
+            self.assertIsNotNone(resets.weekly_block_reason(usage(used, at), now))
+        self.assertIsNotNone(resets.weekly_block_reason({}, now))
+
+    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)
+        atomic_json(
+            self.home / "fake-history.json",
+            {
+                "threads": {},
+                "calls": [],
+                "reset_credit_count": 1,
+                "reset_weekly_used": 100,
+                "reset_weekly_at": time.time() + 72 * 3600,
+            },
+        )
+        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()