gh-glance 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-19
+
+### Fixed
+
+- **Concurrent panes preserve a hard reserve instead of slowing all the way to
+  exhaustion.** Local panes on one GitHub host and account now share atomic
+  grants, worst-case reservations, and one budget probe. gh-glance starts no
+  request when its latest fresh, conservatively debited REST or GraphQL sample
+  cannot pay for it outside the final 20% of that resource. Missing, corrupt,
+  locked, or unwritable coordination fails closed. REST exhaustion does not
+  stop healthy GraphQL tabs, and manual refresh cannot bypass the hold.
+
+### Changed
+
+- **Startup, reset, polling, and status now reflect the shared safe schedule.**
+  Stable pane phases spread startup and post-reset work, active checks precede
+  one rotating background check, and the old 60-second pacing ceiling is gone.
+  The active footer says Watching, Checking, Waiting, Paused, Failed, or Limited.
+  Startup and manual Checking animate while admitted; adapted automatic checks
+  and non-working states stay static. `next HH:MM` names one current grant, not
+  a recurring interval.
+
 ## [0.9.1] - 2026-08-11
 
 ### Fixed
@@ -712,7 +734,8 @@ engineering, security, QA and UX. What follows is what changed as a result.
 - The `main` field from `package.json`. It advertised the file as importable,
   but importing it took over the terminal or exited the host process.
 
-[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.9.1...HEAD
+[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/juan294/gh-glance/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/juan294/gh-glance/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/juan294/gh-glance/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/juan294/gh-glance/compare/v0.7.0...v0.8.0

package/README.md

@@ -11,31 +11,35 @@
 
 A live-refreshing GitHub dashboard that fits in a narrow terminal pane --
 **Actions, Issues, Pull Requests, and Security alerts**, one tab at a time,
-refreshing every 5 seconds with no flicker.
+with a healthy single-pane refresh floor of 5 seconds and no flicker. Shared
+budget coordination can schedule a later safe check when several panes or other
+tools use the same GitHub account.
 
 Built for pairing with a terminal multiplexer/workspace tool (e.g. a sidebar
 pane next to your editor) where you want an always-on glance at repo activity
 without switching to the browser.
 
 ```
-[1:Actions (4)]   2:Issues (3)    3:PRs (2)    4:Security (0)
-────────────────────────────────────────────────────────────────────────────
-╭─ Actions ────────────────────────────────────────────────────────────────╮
-│     TITLE                   │WORKFLOW  │BRANCH        │TIME   │UPDATED   │
-│ ──────────────────────────────────────────────────────────────────────── │
-│ >+  ci: pin actions to comm… #443 CI    develop        1m20s   9d ago    │
-│  x  fix: restore the primar… #442 Code… develop        1m28s   9d ago    │
-│  !  chore: bump dependencies #441 CI    dependa…int-10 222h8m  9d ago    │
-│  -  docs: update the readme  #440 CI    develop        15s     10d ago   │
-│                                                                          │
-│                                                                          │
-╰───────────────────────────────────────────────────────────────── 4 of 4 ─╯
-⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Width: w | Quit: q     0.9.1
+[1:Actions (4)]   2:Issues    3:PRs    4:Security
+───────────────────────────────────────────────────────────────────────────
+╭─ Actions · owner/repo ──────────────────────────────────────────────────╮
+│     TITLE                  │WORKFLOW  │BRANCH        │TIME   │UPDATED   │
+│ ─────────────────────────────────────────────────────────────────────── │
+│ >+  ci: pin actions to com… #443 CI    develop        1m20s   17d ago   │
+│  x  fix: restore the prima… #442 Code… develop        1m28s   17d ago   │
+│  +  chore: bump dependenci… #441 CI    dependa…int-10 30s     18d ago   │
+│  -  docs: update the readme #440 CI    develop        15s     18d ago   │
+│                                                                         │
+│                                                                         │
+╰──────────────────────────────────────────────────────────────── 4 of 4 ─╯
+· Watching  Refresh: r Quit: q Move: ↑↓ Open: Ent Width: w           0.10.0
 ```
 
-> Captured from a real run at 76 columns with `GH_GLANCE_ICONS=unicode`, so the
-> status icons render in a browser. With a Nerd Font (the default) they are
-> Octicon glyphs instead.
+> Generated from this candidate's real binary under the repository PTY harness
+> at 76 columns, using its deterministic fixture data and
+> `GH_GLANCE_ICONS=unicode`; the repeatable command is in
+> [CONTRIBUTING.md](./CONTRIBUTING.md). With a Nerd Font (the default), row
+> icons are Octicon glyphs instead.
 >
 > The `>` on the first row is the cursor. Four more markers appear when they
 > apply: a `+` after a tab's count means the list was truncated by the fetch
@@ -79,10 +83,13 @@ current.
   mode, and preferences kept separately for each tab
 - `lazygit`-style panel frame: the tab name sits in the top border, the
   visible-of-total row count in the bottom
-- A `Fetching` indicator that brightens while a tab's first request is settling
-  or during a manual refresh. Settled automatic polls do not flash it; the
-  spinner still animates during first load or while a workflow run is executing
-- Status icons are real GitHub Octicons (via the Nerd Font glyph set), not emoji
+- A semantic footer for the active tab: **Watching** is settled; **Checking**
+  means admitted work is live; **Waiting** means a probe or future grant;
+  **Paused** protects a held or unavailable budget; **Failed** names a normal
+  fetch error; and **Limited** means Security visibility is incomplete. Startup
+  and manual Checking can animate. Adapted automatic checks, Waiting, Paused,
+  Failed, Limited, and Watching are static
+- Row state icons are real GitHub Octicons (via the Nerd Font glyph set), not emoji
   -- with a plain-ASCII fallback for terminals without one
 - Readable without colour: severity has its own column, a failing newest run puts
   a `!` on the Actions tab, and the active tab is bracketed, so `NO_COLOR=1` and
@@ -108,7 +115,7 @@ current.
   a GitHub Enterprise or EMU tenant -- see [GitHub Enterprise and
   EMU](#github-enterprise-and-emu))
 - A terminal font with [Nerd Font](https://www.nerdfonts.com/) glyphs (for the
-  status icons to render correctly -- without one, they'll show as blank
+  row icons to render correctly -- without one, they'll show as blank
   boxes; see [Icons without a Nerd Font](#icons-without-a-nerd-font))
 
 ## Install
@@ -240,7 +247,7 @@ stdout isn't a terminal rather than streaming redraw frames into a pipe.
 | `↑` / `↓` or `j` / `k` | Move the cursor between rows |
 | `PgUp` / `PgDn` | Move a page at a time |
 | `Enter` | Open the selected item, or accept an onboarding prompt |
-| `r` | Refresh the current tab now |
+| `r` | Request a current-tab refresh; a safe grant is still required. |
 | `w` | Adjust table column widths |
 | `?` | Show the keys without leaving the dashboard (any key closes it) |
 | `q` / `Esc` / `Ctrl+C` | Quit (`Esc` leaves width mode) |
@@ -310,7 +317,7 @@ pane definition. Flags are there when you want them:
 | Flag | Effect |
 |---|---|
 | `-R`, `--repo [host/]owner/name` | Watch a specific repository instead of the current directory's. Works from anywhere -- you do not need a local clone. The optional host targets a GitHub Enterprise or EMU data-residency tenant, e.g. `tenant.ghe.com/acme/widget`. |
-| `--refresh <seconds>` | Active-tab poll interval, 2-3600, default 5. Background tabs stay at 12x this. |
+| `--refresh <seconds>` | Minimum active-tab poll interval, 2-3600, default 5. Safe shared grants can make a check later; each background tab is considered about every 12 floors. |
 | `--tab <name>` | Start on `actions`, `issues`, `prs` or `security`. |
 | `--verbose` | Log one line per `gh` call to stderr, with timing and outcome. stderr must be redirected: `gh-glance --verbose 2>gh-glance.log`. |
 | `--doctor` | Print a diagnostic report and exit. See [Diagnostics](#diagnostics). |
@@ -321,13 +328,14 @@ Environment variables work too, and the flags take precedence:
 
 | Variable | Effect |
 |---|---|
-| `GH_REPO=owner/name` | Watch a specific repository instead of the current directory's. A host-qualified `GH_REPO` does **not** route the security-alert endpoints -- use `GH_HOST` or `--repo host/owner/name` for that |
-| `GH_HOST=<host>` | Send every call to a GitHub Enterprise or EMU host instead of `github.com`. Routes both the list commands and the alert endpoints |
-| `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` | Used by `gh`. gh-glance never logs or stores these values, but hashes each set value locally as part of the account-scoped cache namespace so panes with different credentials cannot hydrate each other's rows. The raw values are not written to disk. |
-| `GH_CONFIG_DIR` | Selects `gh`'s account configuration and contributes its normalized identity to the cache namespace. Separate values can isolate simultaneous panes on different accounts; see [No account pinning](#limitations). |
-| `GH_GLANCE_REFRESH=<seconds>` | Active-tab poll interval, 2-3600. Sets it once for every pane in a shell; `--refresh` takes precedence. This is a floor -- see [Rate limit](#rate-limit) |
-| `GH_GLANCE_ICONS=unicode` | Plain ASCII status icons, for terminals without a Nerd Font |
-| `GH_GLANCE_NO_ANIMATION=1` | Freeze the spinner — no motion at all |
+| `GH_REPO=[host/]owner/name` | Watch a specific repository instead of the current directory's. A qualified value supplies the host; an unqualified value means `github.com`. An explicit `--repo` wins. |
+| `GH_HOST=<host>` | When no explicit `--repo` overrides it, send every call and the account governor to a GitHub Enterprise or EMU host instead of `github.com`. |
+| `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` | Used by `gh`. gh-glance never logs or stores these values, but hashes each set value locally as part of the account-scoped cache and governor namespaces so panes with different credentials cannot share rows or admission. The raw values are not written to disk. |
+| `GH_CONFIG_DIR` | Selects `gh`'s account configuration and contributes its normalized identity to the cache and governor namespaces. Separate values can isolate simultaneous panes on different accounts; see [No account pinning](#limitations). |
+| `GH_GLANCE_REFRESH=<seconds>` | Minimum active-tab poll interval, 2-3600. Sets the floor for every pane in a shell; `--refresh` takes precedence. See [Rate limit](#rate-limit). |
+| `GH_GLANCE_ICONS=unicode` | Unicode status glyphs and single-cell text substitutes for Nerd Font row icons |
+| `GH_GLANCE_ICONS=ascii` | ASCII-only status and row icons |
+| `GH_GLANCE_NO_ANIMATION=1` | Stop status and run-state motion. Semantic words such as Checking, Waiting, and Paused still report what is happening. |
 | `NO_COLOR=1` | Disable colour. Status stays readable: severity has its own column, a failing newest run puts a `!` on the Actions tab, and the active tab is bracketed. Note that run-state glyphs are not all distinct -- see the feature list above |
 | `INK_SCREEN_READER=true` | Switch the renderer to a linear, unthrottled mode. Automated PTY coverage checks that status and selection labels reach this Ink path, but it has not been validated with real assistive technology — treat it as automated rendering coverage, not claimed screen-reader support. |
 
@@ -386,6 +394,31 @@ The cache merges independent targets and tabs, while preferences merge columns,
 so simultaneous panes do not overwrite one another's unrelated state. It is
 recovery state owned by the UI, not a configuration interface.
 
+### Private API governor state
+
+API admission uses a separate file beside the cache:
+
+```text
+$XDG_CONFIG_HOME/gh-glance/rate-governor-v1-<scope hash>.json
+~/Library/Application Support/gh-glance/rate-governor-v1-<scope hash>.json
+~/.config/gh-glance/rate-governor-v1-<scope hash>.json
+```
+
+The hash binds the effective GitHub host to the local `gh` account namespace
+without putting either raw value in the file name. The file records only the
+protocol needed to coordinate panes: REST and GraphQL budget observations and
+epochs, leases, intents, reservations, fair-lane cursors, probe ownership and
+outcomes, and temporary rate-limit blocks. It stores no token, raw host, login,
+repository, working directory, title, author, branch, alert, or other dashboard
+row. Ephemeral lock records contain only a PID and random nonce.
+
+This state has a stricter role than `dashboard-cache.json`. A missing cache can
+be ignored because it only supplies last-good rows. Missing governor state can
+be initialized under its private lock, but corrupt, stale, locked, or unwritable
+coordination fails closed: quota-consuming calls wait or pause instead of
+falling back to independent polling. On POSIX systems the directory is `0700`,
+and governor, temporary, lock, recovery, and quarantine files are `0600`.
+
 ## GitHub Enterprise and EMU
 
 **The common case needs no configuration.** Authenticate once --
@@ -408,11 +441,19 @@ The `[host/]owner/name` form is the same one `gh --repo` accepts. The host must
 contain a dot, so `owner/name/extra` is still rejected as the typo it is rather
 than read as a request to a host named `owner`.
 
-**`GH_HOST` works too**, and is the better lever when every repository you watch
-lives on one enterprise host -- it routes the list commands and the alert
-endpoints alike. A host-qualified **`GH_REPO`**, by contrast, does *not* route
-`gh api`: it supplies the owner and repository and ignores the host, which is
-why `--repo` is the right tool for a one-off cross-host target.
+**Every call and its governor use one effective host.** Resolution is explicit
+and fail-closed: an explicit `--repo host/owner/name` uses that host, while an
+explicit unqualified `--repo owner/name` means `github.com` even when `GH_HOST`
+or `GH_REPO` is also set. Without `--repo`, `GH_HOST` is next, followed by a
+qualified or unqualified `GH_REPO`, then one unambiguous host found across all
+local remotes. An invalid present `GH_HOST`, or ambiguous remotes with no
+explicit choice, cannot silently fall through to another server.
+
+The resolved host routes list commands, alert endpoints, the free rate-limit
+probe, and the shared account governor together. This corrects `gh api`'s native
+behavior for host-qualified `GH_REPO`: gh-glance adds the required `--hostname`
+itself. A running pane also rechecks the active account namespace and moves to a
+fresh closed scope after `gh auth switch`, before it can receive another grant.
 
 **SAML sessions expire.** When an enterprise session lapses, the endpoints
 answer 403 and the tab shows the real `gh` message. Re-authorize in the browser
@@ -427,11 +468,21 @@ gh-glance --doctor > report.txt
 
 Collects, in one plain-text block: the `gh-glance`, Node and `gh` versions;
 which hosts `gh` is authenticated for; how the repository target resolved and
-from where; your remaining REST and GraphQL budget plus what this configuration
-will spend per hour; the relevant environment variables; a read-only
-`Repository access` probe; and each bounded dashboard probe, including the
-Security priority lanes, with the exact argv it sent, its outcome, and how any
-error was classified (`unavailable`, `rate-limited`, `auth-problem` or `other`).
+from where; your remaining REST and GraphQL budget plus the configuration's
+unpaced cost projection; shared governor health; the relevant environment
+variables; a read-only `Repository access` probe; and each bounded dashboard
+probe, including the Security priority lanes, with the exact argv it sent, its
+outcome, and how any error was classified (`unavailable`, `rate-limited`,
+`auth-problem` or `other`).
+
+Doctor first makes one free `rate_limit` request to the effective host. It then
+uses an ephemeral governor lease and admits every quota-consuming endpoint at
+its exact declared cost. A probe whose safe slot is later, whose resource is
+held, or whose budget is unavailable is reported as `SKIPPED`; diagnostics do
+not bypass the reserve. The `API governor` section reports `healthy`, `waiting
+for probe`, `stale`, `blocked`, or `unavailable`, plus the number of live leases
+and each resource's remaining calls, hard reserve, and reset. It does not print
+the scope hash, account identity, state path, lock owner, or reservation IDs.
 
 The `Repository access` probe shows whether the target resolves for the active
 `gh` credentials. A failed GitHub resolution response cannot distinguish a
@@ -456,13 +507,18 @@ printed if `gh-glance` crashes.
 
 ## Rate limit
 
-The visible tab refreshes every 5 seconds; the other three refresh every 60
-seconds, purely to keep their counts honest.
+The default five seconds is a healthy single-pane floor, not an unconditional
+request frequency. Each check first needs an atomic grant from the private
+governor shared by local panes using the same effective host and account
+namespace. The active tab is considered at its floor. One rotating inactive tab
+is considered every four floors, so each of the three background tabs is
+considered about every 12 floors without starting them together.
 
-The tabs do not all draw on the same budget. Actions and Security spend REST
-calls; Issues and Pull Requests are sorted with `--search`, which routes them
-through GraphQL instead — a separate 5,000/hour allowance. With the default
-5-second refresh:
+The resources are independent. Actions and Security spend REST `core` calls;
+Issues and Pull Requests are sorted with `--search`, which routes them through
+GraphQL. The following table is the conservative demand before shared pacing,
+not a promise that the governor will start every listed request. At the default
+floor:
 
 | Visible tab | REST / hour | GraphQL / hour |
 |---|---|---|
@@ -475,16 +531,37 @@ full uses the three base endpoint calls and lands near 2,280 REST requests per
 hour. A full page activates bounded critical/high lanes for Dependabot and code
 scanning, raising the safe projection to about 4,440. Actions is not cheap
 either: one `gh run list` issues two REST requests. `gh-glance --doctor` reports
-the conservative projection beside the server's actual REST and GraphQL
-budgets, which matters on a GitHub Enterprise tenant where the ceilings may not
-be 5,000.
+this projection beside the server's actual REST and GraphQL budgets. Enterprise
+ceilings can differ from 5,000.
 
-Two things pull the real number down. Any endpoint that fails in a way
-`gh-glance` recognises backs off instead of being re-asked every tick — a
-feature that is not enabled for the repository retries on a ladder up to an
-hour, an authorization failure every 30 seconds, a rate limit every minute.
-Pressing `r` clears that backoff and retries immediately. And `--refresh`
-scales the whole figure: doubling the interval halves it.
+For each resource, gh-glance reserves 20% of the reported limit for other work:
+
+```text
+reserve = ceil(limit * 0.2)
+spendable = max(0, remaining - reserve - charged reservations)
+```
+
+That is 1,000 calls for a normal 5,000-call resource. Before any quota-consuming
+`gh` process starts, its declared worst-case REST/GraphQL cost must fit inside
+the latest fresh observation without entering the reserve. A grant is charged
+immediately, then reconciled only when completion evidence proves a lower cost.
+Started, interrupted, or process-lost work stays conservative until a later
+clean probe can account for it. Missing, stale, corrupt, locked, or unwritable
+coordination denies the call instead of returning to five-second polling.
+
+One pane owns the free `rate_limit` probe for a control window and publishes it
+for the others. Manual and diagnostic work is considered before tab-switch,
+active, and background work; equal-priority panes rotate fairly. Manual `r`
+coalesces repeated presses, gives immediate Waiting or Paused feedback, and
+clears an endpoint backoff only after admission. It cannot bypass a held budget
+or force a request into the reserve.
+
+The shared lane uses spendable capacity, time to reset, outstanding
+reservations, and observed external spend. Startup and each new reset epoch add
+a stable per-pane phase, so panes do not resume as a herd. There is no
+60-second maximum: if the next safe slot is farther away, the pane waits that
+long. `next HH:MM` is the time of one current grant, not a promise of a recurring
+poll at that time or interval.
 
 When a refresh fails, the last successful rows stay visible below the live
 error instead of disappearing. If gh-glance is restarted while GitHub is still
@@ -493,18 +570,16 @@ age remains explicit through the `stale` label, and the rate-limit banner still
 describes the current failed request; cached data never turns a failure into a
 false success.
 
-One pane on Actions costs about a third of an hourly REST budget, so roughly
-three panes fill it. Past that, `gh-glance` widens its own poll interval: it
-reads your remaining budget once a minute, works out how much of it belongs to
-this pane by comparing its own spend against the token's total, and slows down
-to fit -- up to a 60-second ceiling. The status bar says `throttled 18s` while
-that is in effect, and `r` still refreshes immediately. Nothing is shared
-between panes: the token's own counter is what they all read, so it also notices
-a `gh pr checks --watch` or anything else spending on the same token.
+The enforceable boundary is local admission from fresh, conservatively debited
+evidence. Another program can spend after the probe, and panes on another
+machine or in a different local account scope cannot share this file. GitHub
+does not offer an atomic global quota reservation. The token-wide counter still
+lets gh-glance measure external use and reduce future capacity, but the hard
+reserve is not a claim that unrelated consumers can never cross it.
 
 `GH_GLANCE_REFRESH=30` sets a wider floor for every pane in a shell; `--refresh`
-still wins per pane. The adaptive interval only ever widens from that floor, so
-a single pane on a healthy budget stays at 5 seconds and shows no badge.
+still wins per pane. A single pane on a healthy budget normally stays at its
+floor and shows Watching between checks.
 
 ## Limitations
 
@@ -559,20 +634,26 @@ a single pane on a healthy budget stays at 5 seconds and shows no badge.
 
 ### Icons without a Nerd Font
 
-The status icons are Octicon glyphs from the [Nerd
+The row icons are Octicon glyphs from the [Nerd
 Fonts](https://www.nerdfonts.com/) private-use-area range. If your terminal
-font isn't a Nerd Font they render as blank boxes -- which would leave status
+font isn't a Nerd Font they render as blank boxes -- which would leave row state
 carried by the colour of a blank box, and by nothing at all under `NO_COLOR`.
 
-Set `GH_GLANCE_ICONS=unicode` for plain ASCII equivalents:
+Set `GH_GLANCE_ICONS=unicode` for Unicode status glyphs and single-cell text
+substitutes for the Nerd Font row icons:
 
 ```bash
 GH_GLANCE_ICONS=unicode gh-glance
 ```
 
-They are deliberately single-cell ASCII rather than prettier symbols like `✓`
-and `✗`, because those are East-Asian-Ambiguous width and render two cells wide
-in some terminals, which would shift every column to their right.
+The row substitutes are deliberately single-cell ASCII rather than symbols like
+`✓` and `✗`, because those are East-Asian-Ambiguous width and render two cells
+wide in some terminals. Use `GH_GLANCE_ICONS=ascii` when the status glyphs must
+also stay within plain ASCII:
+
+```bash
+GH_GLANCE_ICONS=ascii gh-glance
+```
 
 ## Troubleshooting
 
@@ -585,16 +666,20 @@ in some terminals, which would shift every column to their right.
 | `Repository not found or inaccessible to the active gh account` | The active identity cannot resolve the target. Check `gh auth status`, `git remote -v` or the explicit `--repo`, and use `gh auth switch` only if the wrong account is active. |
 | `GraphQL: Could not resolve to a Repository...` in older gh-glance versions | The response has the same ambiguity: a missing or renamed target, or a private repository not visible to the active account. Run `gh-glance --doctor`. |
 | Actions says `not available for this repository` while Repository access is `ok` | The repository resolved, but that endpoint is unavailable; inspect the corresponding doctor block. |
-| Status icons are blank boxes | Your terminal font is not a Nerd Font. Use `GH_GLANCE_ICONS=unicode`. |
+| Row icons are blank boxes | Your terminal font is not a Nerd Font. Use `GH_GLANCE_ICONS=unicode`. |
 | Security tab shows a "not enabled" note | Code scanning and secret scanning need GitHub Advanced Security. Dependabot alerts work independently. The note now appears only when the feature genuinely is unavailable: auth, SSO and network failures show the real error instead. |
 | `none of the git remotes ... point to a known GitHub host` | `gh` is not authenticated for that host. Run `gh auth login --hostname <host>`. |
-| Security tab empty on an enterprise host, other tabs fine | The alert endpoints were sent to the wrong host. Use `--repo host/owner/name` or set `GH_HOST` -- a host-qualified `GH_REPO` alone does not route them. |
+| Security tab empty on an enterprise host in an older gh-glance version | Older versions could route alert endpoints separately. Current gh-glance routes every API call and the governor to one effective host; use `--repo host/owner/name`, `GH_HOST`, or a qualified `GH_REPO`, then confirm the resolved host with `--doctor`. |
 | Tabs start failing after working for a while | The enterprise SAML session lapsed. Re-authorize in the browser; the dashboard recovers within about 30 seconds. Run `gh-glance --doctor` to confirm. |
 | A tab's count is red | That tab's last fetch failed. The error itself is shown when you switch to it, translated into what to do about it where `gh-glance` recognises the failure. |
 | Security tab shows `?` instead of a number | The alert endpoints could not be read at all -- an expired SAML session, a token without `security_events`, or an org OAuth restriction. `?` means "unknown", not "zero"; run `gh-glance --doctor` to see which probe failed and how it was classified. |
-| A failing tab seems to have stopped retrying | It backs off deliberately, rather than re-spawning `gh` every five seconds against an endpoint that is refusing. Press `r` to clear the backoff and retry now. |
+| `Waiting` or `next HH:MM` | The active tab is waiting for a shared budget probe or for its current safe grant. The time names this grant only; it is not a recurring polling interval. Pressing `r` raises safe priority but cannot bypass the lane or reserve. |
+| `Paused` with a reset time | The active tab's REST or GraphQL resource is at its reserve, exhausted, or under a shared rate-limit block. Wait for the stated reset/probe. Other tabs can continue when they use the healthy resource. |
+| `Paused` without a reset time | Budget or coordinator evidence is unknown, corrupt, locked, or unwritable. No data call is started. Run `gh-glance --doctor`; also check the config directory permissions and whether another live process owns its private lock. |
+| A failing tab seems to have stopped retrying | Recognized endpoint failures back off rather than re-spawning `gh` at the floor. Press `r` to request a higher-priority retry; the backoff clears only after a safe grant, so a held budget remains Waiting or Paused. |
 | `unknown argument: -v` | `-v` used to mean `--version` and no longer does, because this CLI also has `--verbose`. Use `--version` or `--verbose` explicitly. |
-| `stale 2m` in the status bar | The visible tab has not refreshed successfully for a while — usually a network drop or rate limit. Last-known-good rows can remain visible, including after restart; the live error above the table explains why they are stale. |
+| Cached rows plus `Paused` and `stale 2m` | The rows came from the separate last-known-good dashboard cache, while the live request is blocked or unsafe. Stale age is not extended by a pause. The error and footer describe current coordination; cached data never means the live check succeeded. |
+| Repeated GitHub rate-limit messages | A classified rate-limit response is published as one shared resource block. Local panes make no data retry before that block's probe/reset deadline. Use `--doctor` to inspect the resource and reset; repeated manual refresh cannot override it. |
 | It exits immediately when piped | Intentional. It is a full-screen dashboard, not a reporting command. |
 | It stopped updating and you cannot tell why | Run `gh-glance --verbose 2>gh-glance.log`, reproduce, then read the log: one line per `gh` call with its duration and outcome. It is redacted the same way `--doctor` is, so it is safe to attach to a bug report. `--doctor --verbose` logs the probes too. |
 | `--verbose` refuses to start | stderr is still your terminal, where the log would draw over the dashboard. Redirect it to a file. |