cdx-manager 0.26.6 → 0.26.8

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.26.6-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.26.8-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 
@@ -42,6 +42,41 @@ cdx work
 
 CDX checks authentication before interactive launches. Handoff keeps the source transcript in place and asks the receiving agent to verify the conversation and workspace before acting. No account switch or prompt submission happens just because you run `cdx next`.
 
+## Quota provenance in status JSON
+
+Every profile in `cdx status --json` (including `--cached` and a named profile)
+includes `quota_windows.5h` and `quota_windows.weekly` alongside the existing
+percentage, reset and timestamp fields. Each window contains:
+
+- `source`: `codex_rate_limits` for the existing `account/rateLimits/read`
+  reader, `claude_probe` for the existing one-token Claude probe,
+  `claude_statusline` for explicitly identified Claude statusline evidence,
+  `cache` for legacy/local evidence without a known provider origin, or
+  `unknown` when the window has no measurement. A cached reading retains its
+  known original source; no extra probe is performed for this metadata.
+- `observed_at`: the ISO 8601 measurement time for this profile and window,
+  or `null` when absent or unknown. Reading a cache never advances this time.
+- `availability`: `measured` below the freshness threshold, `stale` at or
+  beyond it (or when a value has no valid observation time), or `unavailable`
+  when no value exists or the current read/authentication attempt failed.
+- `reason`: `null` unless unavailable; otherwise a stable explanation such
+  as `missing_window`, `login_required`, `login_expired`, `quota_read_failed`,
+  `probe_timeout`, `auth_probe_failed`, `profile_disabled`, or the Codex
+  diagnostic reason (`auth_locked`, `initialize_failed`,
+  `rate_limits_read_failed`, `missing_rate_limits`, `codex_cli_not_found`,
+  `missing_auth_home`, `probe_failed`). Provider error bodies are not copied.
+
+Freshness thresholds match the existing cache TTLs: Codex **300 seconds**,
+Claude **600 seconds**, and other providers **60 seconds** for these generic
+window fields. Provider-specific fields such as Antigravity's quota freshness
+retain their existing semantics. Missing windows remain `null`, never an
+assumed 0% or 100%. On a failed refresh, existing cached percentages and reset
+times remain available for compatibility, but the new availability is
+`unavailable` with the failure reason and the original observation time.
+Transient read errors describe the current command; `--cached` evaluates the
+stored evidence and authentication state without making a new read attempt.
+Reset times describe the quota window, not when it was measured.
+
 ## Automatic mission concurrency per profile
 
 ```bash
@@ -85,6 +120,14 @@ cdx run work --cwd /path/to/repo --prompt "Implement the change" --reasoning-eff
 cdx run --continue-run RUN_ID --cwd /path/to/repo --prompt "Fix the remaining test failure" --json
 ```
 
+Pass provider arguments for a single run with `--extra-args 'ARGS'`. They use the session setting's POSIX quoting and validation (nonempty, at most 512 characters, no control characters, balanced quotes), and are appended after the profile's `extra_args`. They do not change the profile or subsequent interactive launches. Provider flag semantics remain unvalidated, as listed under `unvalidated.extra_args` in `cdx schema --json`; existing provider permission and workspace isolation handling still applies. Codex headless launches retain their existing behavior of ignoring session and run extra arguments.
+
+```bash
+cdx run claude-work --cwd /path/to/repo --permission default --prompt 'Run: touch t' --extra-args '--allowedTools "Bash(touch t)" --strict-mcp-config' --json
+```
+
+This allows the requested Claude tool and restricts MCP configuration for this run only. The option also follows detached runs and profile failover. With `--continue-run`, Claude extra arguments that override model, effort or conversation are refused, whether supplied by the session or this run.
+
 `--continue-run` resumes the exact Claude session or Codex thread and pins the previous run's recorded model and effort, even if the profile settings changed. The profile is inferred from the parent; an explicit session or provider must match. An explicit model or effort must also match. Runs and history record `parent_run_id` and `conversation_id`. Detached continuations use the cdx child supervisor with the same pins. Codex continuation usage is measured between exact transcript snapshots before and after the run, since exec resume can report conversation totals. If either boundary is unavailable, per-run usage stays unknown with `usage_attribution: "continuation_usage_unavailable"` in history instead of counting earlier turns again.
 
 Headless runs, including detached, remote and continued runs, keep their
@@ -358,3 +401,41 @@ next_page = read_conversation(
     cursor=page["next_cursor"], limit=100,
 )
 ```
+
+### Claude quota status line
+
+cdx installs a cache-only `statusLine` command in each new Claude profile's
+`.claude/settings.json` and updates it on copy, rename, import, interactive launch/resume or `cdx set` /
+`cdx unset`. Existing profiles pick it up at their next interactive launch.
+The line uses the launcher's eight-cell remaining-capacity gauge, for example:
+
+```text
+█▁▁▁▁▁▁▁  5h 25% · wk 16% (reset Nov 07 09:30) · grif
+```
+
+The gauge follows the lowest known window. Each window below 20% includes its
+cached reset time when available. `stale` marks observations at least ten minutes
+old, missing an observation timestamp, or dated in the future. Missing, unreadable,
+malformed, or unknown quota data produces only `quota ?`, with no error output.
+The status command reads `sessions.json` directly without taking a store lock,
+refreshing authentication, starting a provider, or making a network call. Refresh
+quota separately with `cdx status --refresh` or the tray's normal refresh cycle.
+It targets less than 100 ms per render; Claude's input JSON is not used.
+
+The command pins the cdx store path and resolves the profile from the session's
+`HOME` / `USERPROFILE`, with `CDX_SESSION_NAME` as fallback when no home is set.
+It does not follow the launcher's currently selected account. Operator-defined
+`statusLine` values and unrelated settings are preserved; cdx reports a conflict
+in launch/settings output (also in JSON `warnings`). Invalid settings are skipped.
+
+```bash
+cdx set grif --status-line off  # Remove only cdx's command and keep it disabled.
+cdx set grif --status-line on   # Reinstall without replacing an operator command.
+cdx unset grif --status-line   # Return to the default (enabled for Claude).
+cdx set --provider claude --status-line on  # Update existing Claude profiles now.
+```
+
+Codex has a built-in status line configured with `tui.status_line`, an ordered list
+of built-in footer item identifiers, rather than Claude's shell-command setting
+([official configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)).
+cdx does not change Codex configuration for this feature.

package/VERSION

@@ -1 +1 @@
-0.26.6
+0.26.8

package/changelogs/CHANGELOGS_0_26_7.md

@@ -0,0 +1,20 @@
+# CDX Manager 0.26.7
+
+Release date: 2026-11-07
+
+## Improvements
+
+- Expose per-profile quota provenance and freshness in status JSON (#118,
+  `3a7a30b4c9b0dce099027be1a6874c2b87d574b6`). Add `quota_windows.5h` and
+  `quota_windows.weekly` with the source, observation time, availability and
+  unavailable reason while preserving existing fields and reset times.
+- Reuse existing quota readers without additional requests. Preserve observation
+  times for cached evidence and mark old or undated readings stale rather than
+  inventing fresh measurements.
+
+## Maintenance
+
+- Record tray companion checksums for v0.26.6
+  (`8e006ca40c942115cac99fd998b6f885358f17f3`).
+- Record release archive checksums for v0.26.6
+  (`0f0c53d2991ef84f368e73b60cb293a94ce4af4d`).

package/changelogs/CHANGELOGS_0_26_8.md

@@ -0,0 +1,19 @@
+# CDX Manager 0.26.8
+
+Release date: 2026-11-07
+
+## Improvements
+
+- Resolve the conversation of a live Codex process (#125,
+  `2150671b`). `cdx conversation <profile> --pid PID` and
+  `--process-identity ID` read the exact conversation of a native Codex
+  process, without falling back to workspace or recency matching.
+- Add per-run provider arguments to `cdx run` (#120, `92620af`).
+  `--extra-args 'ARGS'` is validated like the session setting and appended
+  after the profile's arguments, without changing saved settings or
+  interactive launches.
+
+## Maintenance
+
+- Record tray companion checksums for v0.26.7 (`bd53cb9`).
+- Record release archive checksums for v0.26.7 (`145ec42`).

package/changelogs/CHANGELOGS_UNRELEASED.md

@@ -1,5 +1,23 @@
 # Unreleased
 
+## Per-run provider arguments (#120)
+
+- Add `cdx run --extra-args 'ARGS'` with the session setting's validation and POSIX splitting, appended after the selected profile's arguments without changing saved settings or interactive launches. Preserve existing provider permission and isolation handling.
+- Forward run arguments to detached supervisors and profile failover; reject Claude model, effort and conversation overrides during continuation. List the option under `cdx schema --json` unvalidated arguments and cover run-only Claude tool allowlists and strict MCP configuration.
+
+## Claude profile quota status line
+
+- Install a fast cache-only status line for Claude profiles at creation, settings updates and interactive launch/resume. Show the shared launcher gauge, both remaining windows, profile name, low-quota resets and a stale marker; use `quota ?` when data is unavailable.
+- Preserve and report operator-defined status lines. Add `cdx set --status-line on|off` and `cdx unset --status-line` for reversible profile control; leave Codex settings unchanged and document its built-in footer equivalent.
+- Write the standalone status line as UTF-8 when piped, including on Windows, and read repository contract fixtures explicitly as UTF-8.
+
+
+## Quota provenance and profile freshness
+
+- Add `quota_windows.5h` and `quota_windows.weekly` to status JSON with `source`, per-profile/window ISO `observed_at`, `availability` (`measured`, `stale`, `unavailable`) and a nullable unavailable `reason`. Keep existing fields and reset times compatible.
+- Reuse the existing Codex rate-limit reader and Claude one-token probe without adding requests; distinguish login/read failures and missing windows without inventing percentages. Preserve older window timestamps during backfill.
+- Mark Codex evidence stale at 300 seconds and Claude evidence at 600 seconds (60 seconds for generic other-provider windows); unknown measurement times are stale. Cached evidence retains known provenance and never receives a new observation time.
+
 ## Find and resume interactive sessions
 
 - Add exact resolved `cdx history --cwd PATH` and `--interactive` filters before the result limit, preserving the JSON envelope and period/summary support.

package/checksums/release-archives.json

@@ -859,6 +859,28 @@
         "x86_64-pc-windows-msvc": "1ea355b54e05ea6d78a3a23757a9ad5dd2228aa1d939fb7992082e16da579abb",
         "x86_64-unknown-linux-musl": "770fabb26784efb607d2cce6d6bee51c3d7121283c55cf4cacb9b54ac75e4450"
       }
+    },
+    "v0.26.6": {
+      "github_tarball_sha256": "ac54b4e9cb3ab6eb232d31806fcccb9a56720a3d75ee26cb3b81bd9923dd4ca0",
+      "github_zip_sha256": "6a195d19ee29ef568d43b6edbf23980b29c9fc35f295269b82e1f32ce5b7b490",
+      "tray_assets": {
+        "aarch64-apple-darwin": "4d9be82842365447f4d34ddc577b0571e620c0d900da9f751f50337d3362ff68",
+        "aarch64-unknown-linux-musl": "0c13305e28348578fd7437e319dc53aecc0f1e4b3ff21db25e19a70b2fdc6e8b",
+        "x86_64-apple-darwin": "b7a8d7ea2b3f0e2b8eba08d845eeb7c41e06b8dbfc1915257c920577e23e01d7",
+        "x86_64-pc-windows-msvc": "82fcceda389ba33ef60bc01ccce62249c0a1866479611192761778646ad33880",
+        "x86_64-unknown-linux-musl": "a1194dc6e672729e7d6ba079b7c1a393e7098e83edd6ab3b6fd63832a7dad136"
+      }
+    },
+    "v0.26.7": {
+      "github_tarball_sha256": "26e961c60c2473946cb5bfadec467b4d4ca9fd5a07cd313145cf4c4d427b1239",
+      "github_zip_sha256": "324c8f938f037e19c31b19e9fc6d4721ca822a7aa9a14d8e0e1af8da52aafaad",
+      "tray_assets": {
+        "aarch64-apple-darwin": "80088939f95fb6508f98b1e9a29643372dcc5e4cb2f72f06c5016f1708f6f526",
+        "aarch64-unknown-linux-musl": "29a044fa1241f38ce2892bd37388258ab1f10d66a74c3beef6462d85a8ab52c2",
+        "x86_64-apple-darwin": "d32be4180b361195ec9faef888dc9ff1a996bb74295882008ccb2b07dd16789d",
+        "x86_64-pc-windows-msvc": "098c27b535f041b72b6aac89d2c34464a986178be881336b89f99c8dfb5fdb5d",
+        "x86_64-unknown-linux-musl": "195737be7f25dc30bab676f53aed2c426612aee55de4cfc95a55a5b2d8ca9b76"
+      }
     }
   }
 }

package/docs/cli.md

@@ -58,7 +58,7 @@
 | `cdx agents [--max-age-hours N] [--json]` | Each session's last known agent state (working, waiting, done, failed, limit, ended), waiting first; records older than N hours (default 24) are dropped. See [Agent state](sessions-and-notifications.md#agent-state) |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
-| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--budget USD] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
+| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--budget USD] [--extra-args 'ARGS'] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
 | `cdx run-report <run_id> --json` | Full report, transcript metadata, and final payload for a run; `final_message` is the run's last assistant message, read from Claude's `result` envelope or Codex's last `agent_message` (null when neither exists) |
 | `cdx run-status <run_id> --json` | Status of one run by id |
 | `cdx run-tail <run_id> [--lines N] --json` | Last lines of a run's own output, while it is still running or after it finished |
@@ -683,3 +683,75 @@ Interactive launches appear as `status: "running"` as soon as the provider start
 History entries expose `conversation_id` and `provider_transcript_match: "conversation_id"` when an exact provider transcript exists. Claude uses its launch session ID; Codex can recover a unique thread from transcript metadata matching the launch directory and time window. Ambiguous discovery remains `provider_transcript_match: "recency"`, an explicitly unverified fallback that must not be treated as a verified resume target. A known ID with no transcript does not borrow another conversation. Existing history is enriched on read without rewriting old rows.
 
 `first_user_prompt` contains the first real user text (up to 2,000 characters) from a bounded, redacted transcript read. Provider command wrappers, system reminders, tool results and bare absolute file paths are skipped. Missing, oversized or unavailable evidence leaves the prompt unknown; a supplied initial prompt is used when available.
+
+### Resolve the conversation of a live Codex process
+
+Consumers such as remote-ops can request process-scoped resolution without
+falling back to workspace/recency:
+
+```bash
+cdx conversation work2 --pid 12345 --tail 20 --json
+cdx conversation work2 --process-identity 'linux:12345:<opaque digest from response>' --json
+```
+
+Supply the native Codex PID, not the shell, tmux pane PID, Node launcher, or CDX
+supervisor. CDX does not traverse descendants or choose between processes.
+`work2` supplies the provider/profile boundary; its saved conversation is ignored
+in process mode. The selectors are mutually exclusive and cannot be combined with
+`--conversation`, `--cwd`, or `--since`.
+
+The Python API is `read_conversation("codex", auth_home, pid=12345, tail=20)` in
+`cdx_manager.conversation` (`src.conversation` in a source checkout). Retain
+`process_identity` and pass it instead of `pid` on later calls to reject PID reuse.
+A bare PID identifies its current occupant, not a previously observed process.
+The opaque identity is a lifetime guard, not an authorization grant.
+
+Process-selected pages expose:
+
+| Field | Current contract |
+| --- | --- |
+| `resolution_status` | `unknown` until native selected-conversation evidence is available |
+| `resolution_method` | `null`; kernel process identity alone is not a conversation resolution method |
+| `conversation_id` | `null`; no candidate or guessed ID is exposed |
+| `process_identity` | Opaque Linux lifetime guard when process validation succeeds |
+| `reason` | Explicit evidence boundary or process validation failure |
+
+**Current measured boundary:** process-to-selected-conversation resolution is not
+available. Even a sole open writable rollout proves only that a process owns a
+thread. During a TUI conversation switch it may belong to a retained thread while
+the selected thread has no rollout yet. Resume argv, session/profile state, cwd,
+mtime, a unique new transcript, and fuzzy text also cannot prove the current
+selection. This implementation deliberately returns
+`native_conversation_identity_unavailable` after validating a live Codex process;
+it does not claim that an open file establishes the selected conversation.
+Remote-ops must treat this as an explicit unknown, never retry via recency.
+
+Process mode returns `status: "unavailable"`, empty entries, null conversation ID
+and no cursors. With `--cursor` or `--before`, it returns `reset_required` and no
+entries: a cursor from an explicit-ID or recency lookup cannot cross into process
+mode. No process cursor is issued until it can be bound to both a verified process
+lifetime and a native conversation selection/generation. Existing explicit-ID,
+recency, forward, tail and backward pagination contracts remain unchanged.
+
+Only Linux `/proc` process identity is currently supported. Each validation reads
+at most 8 KiB each from process `stat`, `status` and kernel `boot_id`, twice, plus
+the executable symlink/stat. The guard includes PID, start ticks, boot ID, all
+four target UIDs and executable device/inode. Wrong user, a non-`codex` executable,
+dead/reused PID, inaccessible/oversized/malformed evidence, or unsupported
+provider/platform fails closed. Other reasons include `unrelated_user`,
+`unrelated_process`, `process_not_running`, `process_identity_changed`,
+`native_evidence_unavailable`, `evidence_limit`, and
+`unsupported_process_resolution`. No argv, environment, credential store,
+transcript file, directory scan or history database is read in process mode.
+A process identity does not prove profile ownership; missing native profile and
+thread association therefore remains unknown even for an existing profile.
+
+The smallest required launch-time tracking is a provider-native event containing
+the selected conversation ID on fresh start, resume and every selection change.
+The launcher must bind each event atomically to the child's boot ID/PID/start ticks,
+profile and a monotonic selection generation; invalidate it on exit. A future
+resolver can consume that bounded record and bind cursors to the same generation.
+An original resume ID or launch timestamp alone is insufficient. No launch/resume
+flags or dependencies are changed here; implementing this requires a verified
+provider lifecycle event source, which the inspected interactive interface does
+not supply. See the mission fragment for the local native probe and Tower checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.26.6",
+  "version": "0.26.8",
   "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.26.6"
+version = "0.26.8"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9.2"
@@ -55,6 +55,9 @@ cdx = "cdx_manager.cli:cli_entry"
 # of which ship the source tree wholesale — worked fine.
 packages = ["cdx_manager", "cdx_manager.commands"]
 
+[tool.setuptools.package-data]
+cdx_manager = ["quota_gauge.txt"]
+
 [tool.setuptools.package-dir]
 cdx_manager = "src"
 "cdx_manager.commands" = "src/commands"

package/src/claude_refresh.py

@@ -2,7 +2,7 @@ import inspect
 import threading
 from datetime import datetime, timezone
 
-from .claude_usage import refresh_claude_session_status
+from .claude_usage import ClaudeAuthInvalidError, refresh_claude_session_status
 from .config import PROVIDER_CLAUDE
 from .errors import CdxError
 
@@ -48,6 +48,7 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
 
     errors = []
     results = {}
+    completed = set()
 
     threads = []
 
@@ -61,15 +62,22 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
             # refresh_fn is the real default, since a caller-injected
             # refresh_fn (tests, mocks) may not accept auth_refresher.
             if refresh_fn is refresh_claude_session_status and s["name"] in already_auth_refreshed:
-                usage = refresh_fn(s, auth_refresher=lambda _auth_home: None)
+                usage = refresh_fn(s, auth_refresher=lambda _auth_home: None, diagnostic=True)
+            elif refresh_fn is refresh_claude_session_status:
+                usage = refresh_fn(s, diagnostic=True)
             else:
                 usage = refresh_fn(s)
             if inspect.isawaitable(usage):
                 raise CdxError("Claude refresh function returned an awaitable from a sync callable.")
-            if usage:
+            if usage and usage.get("_quota_error"):
+                errors.append({"session": s["name"], "error": CdxError("Claude quota unavailable"), "reason": usage["_quota_error"]})
+            elif usage:
                 results[s["name"]] = usage
         except Exception as e:
-            errors.append({"session": s["name"], "error": e})
+            errors.append({"session": s["name"], "error": e,
+                           "reason": "login_expired" if isinstance(e, ClaudeAuthInvalidError) else "quota_read_failed"})
+        finally:
+            completed.add(s["name"])
 
     for s in claude_sessions:
         t = threading.Thread(target=fetch, args=(s,), daemon=True)
@@ -83,6 +91,11 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
     results = dict(results)
     errors = list(errors)
 
+    completed = set(completed)
+    for session in claude_sessions:
+        if session["name"] not in completed:
+            errors.append({"session": session["name"], "error": CdxError("Claude quota read timed out"), "reason": "probe_timeout"})
+
     recorded = []
     for name, usage in results.items():
         try:

package/src/claude_status_line.py

@@ -0,0 +1,139 @@
+"""Fast, cache-only Claude status line; executable without importing the CLI."""
+
+import json
+import math
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+MARKER = "--cdx-claude-status"
+CACHE_TTL_SECONDS = 10 * 60  # Same freshness window as Claude's cached status.
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return None
+
+
+def _pct(value):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and 0 <= value <= 100 and math.isfinite(value) else None
+
+
+def gauge(value):
+    # The tray menu embeds this same eight-cell glyph strip at build time.
+    full, empty = Path(__file__).with_name("quota_gauge.txt").read_text(encoding="utf-8").splitlines()
+    filled = int(math.floor((value or 0) / 100 * len(full) + 0.5))
+    return full[:filled] + empty[filled:]
+
+
+def _clean(value):
+    return "".join(c for c in str(value) if c.isprintable())
+
+
+def render(base_dir, env=None, now=None):
+    env = os.environ if env is None else env
+    data = _read(os.path.join(base_dir, "sessions.json"))
+    if not isinstance(data, dict) or not isinstance(data.get("sessions"), list):
+        return "quota ?"
+    home = env.get("HOME") or env.get("USERPROFILE")
+    name = env.get("CDX_SESSION_NAME")
+    matches = [s for s in data["sessions"] if isinstance(s, dict) and s.get("provider") == "claude" and (
+        os.path.realpath(s.get("authHome") or "") == os.path.realpath(home) if home else s.get("name") == name
+    )]
+    if len(matches) != 1:
+        return "quota ?"
+    session = matches[0]
+    status = session.get("lastStatus")
+    if not isinstance(status, dict):
+        return "quota ?"
+    values = [_pct(status.get(f"remaining_{window}_pct")) for window in ("5h", "week")]
+    known = [v for v in values if v is not None]
+    if not known:
+        return "quota ?"
+    now = now or datetime.now(timezone.utc)
+    evidence = status.get("quota_windows") or {}
+    stale = False
+    for window, value in zip(("5h", "weekly"), values):
+        if value is None:
+            continue
+        reading = evidence.get(window, {}) if isinstance(evidence, dict) else {}
+        if not isinstance(reading, dict):
+            reading = {}
+        timestamp = reading.get("observed_at", status.get("updated_at") or session.get("lastStatusAt"))
+        try:
+            observed = datetime.fromisoformat(str(timestamp).replace("Z", "+00:00"))
+            stale |= observed.tzinfo is None or not 0 <= (now - observed).total_seconds() < CACHE_TTL_SECONDS
+        except (ValueError, TypeError):
+            stale = True
+        stale |= reading.get("availability") in ("stale", "unavailable")
+    parts = []
+    for window, label, value in zip(("5h", "week"), ("5h", "wk"), values):
+        text = f"{label} {value:g}%" if value is not None else f"{label} ?"
+        reset = status.get(f"reset_{window}_at")
+        if value is not None and value < 20 and reset:
+            text += f" (reset {_clean(reset)})"
+        parts.append(text)
+    parts.append(_clean(session.get("name", "?")))
+    if stale:
+        parts.append("stale")
+    return f"{gauge(min(known))}  " + " · ".join(parts)
+
+
+def provision(session, base_dir):
+    """Return a report on conflicts; never replace an operator's status line."""
+    if session.get("provider") != "claude":
+        return None
+    import shlex
+    import subprocess
+
+    from .agent_notify import _read_json, _write_json
+
+    path = os.path.join(session["authHome"], ".claude", "settings.json")
+    settings = _read_json(path)
+    if settings is None:
+        return f"{session['name']}: statusLine skipped (unreadable settings.json)"
+    current = settings.get("statusLine")
+    own = False
+    if isinstance(current, dict) and isinstance(current.get("command"), str):
+        try:
+            parts = shlex.split(current["command"], posix=os.name != "nt")
+            own = len(parts) == 4 and os.path.basename(parts[1].strip('"')) == "claude_status_line.py" and parts[2] == MARKER
+        except ValueError:
+            pass
+    if "statusLine" in settings and not own:
+        return f"{session['name']}: operator-defined statusLine preserved"
+    if (session.get("launch") or {}).get("status_line") is False:
+        if not own:
+            return None
+        del settings["statusLine"]
+    else:
+        args = [sys.executable, os.path.abspath(__file__), MARKER, os.path.abspath(base_dir)]
+        command = subprocess.list2cmdline(args) if os.name == "nt" else shlex.join(args)
+        desired = {**(current or {}), "type": "command", "command": command}
+        if current == desired:
+            return None
+        settings["statusLine"] = desired
+    if not _write_json(path, settings):
+        return f"{session['name']}: statusLine skipped (settings.json is not writable)"
+    return None
+
+
+def main(argv=None, stdout=None, env=None):
+    argv = sys.argv[1:] if argv is None else argv
+    stdout = sys.stdout if stdout is None else stdout
+    try:
+        text = render(argv[1], env=env) if len(argv) == 2 and argv[0] == MARKER else "quota ?"
+    except (OSError, ValueError, TypeError, AttributeError):
+        text = "quota ?"
+    stdout.write(text + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    # Claude reads UTF-8 from a pipe; Windows otherwise uses its ANSI code page.
+    sys.stdout.reconfigure(encoding="utf-8")
+    raise SystemExit(main())

package/src/claude_usage.py

@@ -15,6 +15,7 @@ except ImportError:  # pragma: no cover - Windows
 
 from .claude_credentials import read_keychain_credentials
 from .errors import CdxError
+from .quota_provenance import quota_windows
 
 MONTH_ABBR = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
@@ -368,7 +369,7 @@ def fetch_claude_rate_limit_headers(access_token):
     reset_week_at = _format_reset_date(_parse_reset_epoch(reset_7d)) if reset_7d else None
     reset_at = reset_week_at or reset_5h_at
 
-    return {
+    status = {
         "remaining_5h_pct": _remaining_from_utilization(utilization_5h),
         "remaining_week_pct": _remaining_from_utilization(utilization_7d),
         "reset_5h_at": reset_5h_at,
@@ -378,20 +379,22 @@ def fetch_claude_rate_limit_headers(access_token):
         "raw_status_text": None,
         "source_ref": "api:anthropic-ratelimit-headers",
     }
+    status["quota_windows"] = quota_windows(status, "claude")
+    return status
 
 
-def refresh_claude_session_status(session, auth_refresher=None):
+def refresh_claude_session_status(session, auth_refresher=None, diagnostic=False):
     auth_home = session.get("authHome", "")
     refresher = auth_refresher or _refresh_claude_cli_credentials
     refresher(auth_home)
     creds = _read_claude_credentials(auth_home)
     if not creds or not creds.get("accessToken"):
-        return None
+        return {"_quota_error": "login_required"} if diagnostic else None
     if _access_token_expired(creds):
         # ponytail: `claude auth status` doesn't refresh an expired access
         # token (verified no-op) and only a real Claude Code invocation does.
         # Probing anyway just reproduces a 401 we can already predict
-        # offline, so skip it like the "no credentials" case above and leave
-        # the cached quota as stale rather than raising a false alert.
-        return None
-    return fetch_claude_rate_limit_headers(creds["accessToken"])
+        # offline, so skip it and retain the cached observation time.
+        return {"_quota_error": "login_expired"} if diagnostic else None
+    status = fetch_claude_rate_limit_headers(creds["accessToken"])
+    return status or ({"_quota_error": "quota_read_failed"} if diagnostic else None)

package/src/cli.py

@@ -266,14 +266,14 @@ def _print_help(use_color=False):
         f"  {_style('cdx configs [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
         f"  {_style(SET_USAGE[len('Usage: '):], '36', use_color)}",
-        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--max-parallel|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--status-line|--notify-preview|--model|--priority|--max-parallel|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx start <name> [--dir PATH] [--resume] [--json]', '36', use_color)}",
         f"  {_style('cdx history backfill-projects [--mapping FILE] [--dry-run|--apply] [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--cwd PATH] [--interactive] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
         f"  {_style('cdx resume <name> [--project PATH] [--conversation <id>] [--json]', '36', use_color)}",
-        f"  {_style('cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json', '36', use_color)}",
+        f"  {_style('cdx conversation <name> [--conversation ID | --pid PID | --process-identity ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--conversation <id>] [--json]', '36', use_color)}",
         f"  {_style('cdx rescue [<session>] [--to <target>] [--yes] [--dry-run] [--json]', '36', use_color)}",
         f"  {_style('cdx retro [--limit N] [--json]', '36', use_color)}",