cdx-manager 0.15.0 → 0.15.1

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.15.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.15.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 

package/changelogs/CHANGELOGS_0_15_0.md

@@ -131,9 +131,14 @@ synthetic home (`scripts/seed_demo_home.py`) so they carry no account names.
 
 ## Known gaps
 
-- The rate-limit wording of a personal-plan Codex account and of Claude has not
-  been observed; only an enterprise workspace out of credits has. The
-  `account_status_exhausted` route covers the unobserved cases, so this costs
-  the precise reason rather than the failover itself.
+- The rate-limit wording of a personal-plan Codex account has not been
+  observed; only an enterprise workspace out of credits has. Claude's wording
+  was recovered from local transcripts after the release was cut - it reports
+  `type: rate_limit_error` under HTTP 429, which the matcher already covers.
+  Worth knowing: that same 429 is also how an org policy disabling a model is
+  reported, a case no failover can fix, and the status corroboration is what
+  stops a healthy account being abandoned for it. The
+  `account_status_exhausted` route covers whatever wording remains unseen, so
+  this costs the precise reason rather than the failover itself.
 - Background delegation has been exercised on one account with one prompt
   shape, which is why it is opt-in.

package/changelogs/CHANGELOGS_0_15_1.md

@@ -0,0 +1,85 @@
+# CDX Manager 0.15.1
+
+> Two fixes, both for failures that only appear under the conditions cdx is
+> built for: an account whose credits ran out while its usage windows still
+> read healthy, and twenty parallel runs writing the registry at once on
+> Windows.
+
+## Fixes
+
+### Failover missed an exhausted account when its windows looked fine
+
+`--failover` corroborates a rate-limited run against the account's own
+refreshed status before migrating, so a healthy account is never abandoned on
+the strength of a matched phrase. That check read only the 5-hour and weekly
+percentages, which cannot see credit exhaustion: an account with 88% of its
+5-hour window and 70% of its weekly window remaining, and no credits, was
+reported as not spent. The run failed instead of moving, on an account that
+could not have succeeded.
+
+Codex publishes a typed reason for this — `rate_limit_reached_type`, null in
+normal operation and set to a value such as `workspace_owner_credits_depleted`
+when a limit is actually reached. cdx was already fetching that payload and
+dropping the field; it survived only inside `raw_status_text`, unparsed. It is
+now surfaced and treated as authoritative.
+
+Any non-null value counts. The enum belongs to the provider, and carrying a
+list of its members in cdx would reintroduce exactly the drift this removes —
+a value nobody has seen yet would silently mean "not exhausted".
+
+### Concurrent registry writes failed on Windows
+
+`_registry_lock` used `msvcrt.locking(LK_LOCK)`, which does its own waiting —
+ten attempts, one second apart — and then raises `EDEADLOCK`. POSIX
+`fcntl.flock` blocks until the lock frees. Identical contention therefore
+produced a wait on one supported platform and an `OSError` on the other.
+
+Twenty parallel runs writing the run registry is not an edge case for this
+tool; it is the load it exists to carry. Windows now takes the non-blocking
+form and waits in a loop cdx controls, bounded by a deadline cdx chooses rather
+than by `LK_LOCK`'s fixed budget. An exhausted wait raises a named error
+instead of a raw `OSError`, so contention is distinguishable from a bug.
+
+This predates 0.15.0 — it reproduces on the `v0.14.0` tag — and CI never showed
+it, a hosted runner being less contended than a physical desktop. Which also
+means CI could not be the evidence for the fix.
+
+## Also in this release
+
+- A test now fails if a flag is declared in a parser's schema and never used,
+  which is how `--failover` shipped in 0.15.0 parsing, validating and doing
+  nothing until an integration test caught it by chance.
+- `scripts/measure_option_sites.py` records the measurement behind that
+  decision: of the nine declaration sites an option touches, six restate one
+  fact and three encode a real decision, so the answer was a check rather than
+  a consolidation.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 639 tests.
+- CI green on ubuntu-latest and windows-latest.
+- On a physical Windows machine: 632 passed, 5 skipped, **no failures** —
+  including `test_concurrent_starts_do_not_lose_records`, which had failed
+  there on every run since before v0.14.0.
+- The credit-exhaustion case verified against the real payload shape recovered
+  from local transcripts: with 88% and 70% of the windows remaining and a typed
+  reason present, corroboration now confirms where it previously did not.
+
+## What closed from 0.15.0's known gaps
+
+- **Claude's rate-limit wording** was unobserved and now is not. Recovered from
+  local session transcripts: `type: rate_limit_error` under HTTP 429, already
+  covered by the existing matcher. Worth knowing, and now pinned by tests: the
+  same 429 is how an org policy disabling a model is reported, a case no
+  failover can fix, and the status corroboration is what keeps a healthy
+  account from being abandoned for it.
+
+## Still open
+
+- The rate-limit wording of a personal-plan Codex account remains unobserved.
+  The `account_status_exhausted` route covers it, so this costs the precise
+  reason rather than the failover itself.
+- Background delegation is still opt-in behind `CDX_EXPERIMENTAL_NATIVE_BG=1`.
+  It works and is verified end to end, but on one account with one prompt
+  shape — an exposure judgement, not a correctness one.

package/checksums/release-archives.json

@@ -172,6 +172,10 @@
     "v0.14.0": {
       "github_tarball_sha256": "5da107556442d3566a7b0787708ae700e38afdf99e74209fffd2484ce3a33d94",
       "github_zip_sha256": "bd4e070582bfc641e6176a8b8be8d7afd1ce9d76fc59c1dbeb238bae548bc699"
+    },
+    "v0.15.0": {
+      "github_tarball_sha256": "93d0a7305a5235f20e89a3e2a404029546926437952ee61d43a1f69c3ae98e4e",
+      "github_zip_sha256": "23e4e42fb746f4af5fa407f853e979ffce91e147dbb623c250e276fdcaa9638a"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.15.0"
+version = "0.15.1"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/run_failover.py

@@ -10,7 +10,9 @@ resolves to "not rate limited".
 Signal one is the provider's own structured output, which both headless paths
 already produce - `codex exec --json` emits JSONL events, and the claude spec
 passes `--print --output-format json`. Signal two is the account's rate-limit
-status, refreshed once and read through the existing status pipeline.
+status, refreshed once and read through the existing status pipeline - where
+`rate_limit_reached` is the strongest evidence available, being the provider's
+own typed reason rather than a threshold or a sentence.
 
 The matchers below are deliberately the only place that knows what exhaustion
 looks like on the wire. That shape is version-specific and is the part most
@@ -35,6 +37,14 @@ _MAX_TAIL_BYTES = 64 * 1024
 # "out of credits" was missing from the first version of this list, which is why
 # it never matched anything real. Credit exhaustion and a rate limit are the
 # same thing for this decision: the account cannot serve the task, try another.
+# Claude's own wording, captured from a real transcript on this machine:
+#   API error: 429 {"type":"error","error":{"type":"rate_limit_error",
+#     "message":"Usage credits are required for this model.", ...}}
+# `rate_limit_error` is already covered by "rate_limit" below. Worth knowing:
+# that same 429 is also how an org policy disabling a model is reported
+# (`disabled_reason: org_level_disabled`), which no amount of failing over
+# would fix - every account in the org hits it. The status corroboration in
+# `failover_reason` is what keeps that case from migrating a healthy run.
 _RATE_LIMIT_MARKERS = (
     "out of credits",
     "rate_limit",
@@ -161,6 +171,12 @@ def status_confirms_exhaustion(row):
     """
     if not row:
         return False
+    # The provider's own typed reason, when it gives one. Authoritative and
+    # language-free: `workspace_owner_credits_depleted` says the account cannot
+    # serve the task even when both percentage windows still read healthy,
+    # which is a case the thresholds below would miss entirely.
+    if row.get("rate_limit_reached"):
+        return True
     if row.get("blocking"):
         return True
     for key in ("remaining_5h_pct", "remaining_week_pct"):

package/src/run_registry.py

@@ -2,9 +2,12 @@ import json
 import os
 import sys
 import tempfile
+import time
 from contextlib import contextmanager
 from datetime import datetime, timezone
 
+from .errors import CdxError
+
 
 def utc_now_iso():
     return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
@@ -14,14 +17,49 @@ def registry_path(base_dir):
     return os.path.join(base_dir, "runs.json")
 
 
+# A waiter waits. `fcntl.flock` blocks until the lock is free, but Windows'
+# `LK_LOCK` retries ten times at one-second intervals and then raises
+# EDEADLOCK, so the same contention produced a wait on one platform and an
+# OSError on the other. Twenty parallel runs writing this registry is the load
+# cdx exists to carry, and on a physical Windows machine it exhausted that
+# budget - CI never showed it, being less contended than a real desktop.
+REGISTRY_LOCK_TIMEOUT_SECONDS = 120
+_LOCK_RETRY_SECONDS = 0.05
+
+
+def _acquire_windows_lock(handle, timeout_seconds):
+    """Block until the byte is locked, or give up with a nameable error.
+
+    Uses the non-blocking form and does the waiting here, so the wait is
+    bounded by a deadline cdx chooses rather than by `LK_LOCK`'s fixed ten
+    attempts. Unbounded would be worse than the original: a stuck holder would
+    hang every later command with nothing to report.
+    """
+    import msvcrt
+
+    deadline = time.monotonic() + timeout_seconds
+    while True:
+        handle.seek(0)
+        try:
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            return
+        except OSError:
+            if time.monotonic() >= deadline:
+                raise CdxError(
+                    "Timed out waiting for the run registry lock after "
+                    f"{timeout_seconds}s. Another cdx process may be stuck holding it.",
+                    75,
+                ) from None
+            time.sleep(_LOCK_RETRY_SECONDS)
+
+
 @contextmanager
-def _registry_lock(path):
+def _registry_lock(path, timeout_seconds=REGISTRY_LOCK_TIMEOUT_SECONDS):
     os.makedirs(os.path.dirname(path), exist_ok=True)
     with open(path + ".lock", "a") as handle:
         if sys.platform == "win32":
             import msvcrt
-            handle.seek(0)
-            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+            _acquire_windows_lock(handle, timeout_seconds)
             try:
                 yield
             finally:

package/src/session_status.py

@@ -79,6 +79,7 @@ def _normalize_status_payload(payload=None):
         "reset_5h_at": payload.get("reset_5h_at"),
         "reset_week_at": payload.get("reset_week_at"),
         "reset_at": payload.get("reset_at") or payload.get("reset_week_at") or payload.get("reset_5h_at"),
+        "rate_limit_reached": payload.get("rate_limit_reached"),
         "updated_at": _to_local_iso(payload.get("updated_at") or payload.get("captured_at") or now),
         "raw_status_text": payload.get("raw_status_text"),
         "source_ref": payload.get("source_ref"),

package/src/status_source.py

@@ -153,6 +153,13 @@ def _extract_structured_rate_limits(record):
         "reset_5h_at": _normalize_timestamp_value(_get_rate_limit_reset_at(five_hour)),
         "reset_week_at": _normalize_timestamp_value(_get_rate_limit_reset_at(weekly)),
         "reset_at": None,
+        # A typed reason the account is blocked, when the provider gives one:
+        # null in normal operation, and a value such as
+        # "workspace_owner_credits_depleted" when a limit is actually reached.
+        # Better evidence than any percentage - credits can run out while the
+        # 5-hour and weekly windows still read healthy - and better than
+        # matching prose, since it is an enum rather than a sentence.
+        "rate_limit_reached": _clean_reached_type(rate_limits.get("rate_limit_reached_type")),
         "raw_status_text": json.dumps(rate_limits, sort_keys=True),
     }
     if not five_hour and weekly:
@@ -172,6 +179,13 @@ def _extract_structured_rate_limits(record):
     return result
 
 
+def _clean_reached_type(value):
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    return text or None
+
+
 def _collect_structured_rate_limit_statuses(value, output=None):
     if output is None:
         output = []