npm - gh-glance - Versions diffs - 0.8.0 → 0.10.0 - Mend

gh-glance 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,93 @@ 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
+- **Package-boundary verification supports npm 12.** The release test accepts
+  both npm 11's array-shaped `npm pack --json` result and npm 12's
+  package-name-keyed result, so the existing OIDC publication workflow can
+  verify the CLI-only package boundary before publishing.
+## [0.9.0] - 2026-08-11
+### Added
+- **Security keeps a bounded priority view when newest pages fill.** Dependabot
+  and code-scanning sources add critical/high lanes only when their newest 100
+  open alerts fill the base page, then merge and de-duplicate the result. A `+`
+  marker stays explicit when any lane fills; the app never claims an unbounded
+  repository is complete.
+- **Adaptive polling now protects both GitHub budgets.** REST and GraphQL spend
+  are measured separately, including failed calls, and the safer interval wins
+  without lowering the configured refresh floor. `--doctor` reports the same
+  conservative model.
+- **Terminal state has explicit non-colour and linear-rendering channels.** A
+  stable ASCII `x` marks fetch failure, selected rows include `selected` in
+  their accessibility label, narrow errors begin with the recovery action, and
+  short help always retains Quit, Refresh, and the full-help command.
+- **PTY child-process coverage is available as an informational signal.**
+  `npm run test:coverage:runtime` summarizes observed `index.mjs` functions on
+  scheduled/manual coverage runs without adding a threshold or release gate.
+### Changed
+- **Dashboard recovery state is account-scoped and safe across panes.** Cache
+  version 2 includes `GH_CONFIG_DIR`/`hosts.yml` identity and one-way digests of
+  supported token variables, rejects the old unscoped cache, and uses bounded
+  locked three-way merges so simultaneous panes preserve unrelated targets,
+  tabs, and width choices. Successful quiet polls checkpoint freshness on a
+  bounded cadence.
+- **Settled automatic polling is visually quiet.** `Fetching` is reserved for
+  startup/manual work, unchanged Security observations slow to a 60-second
+  cadence, and cache-hydrated tabs clear their initial loading state.
+- **Mouse reporting is opt-in through Width mode.** Press `w` before dragging a
+  header divider; outside that mode the terminal keeps ordinary mouse behavior.
+- **The npm package is explicitly CLI-only.** The executable remains supported,
+  while package-root and deep JavaScript imports now fail through `exports: {}`.
+### Fixed
+- **Manual Security refresh now clears every source backoff after the in-flight
+  guard admits the request.** Re-authenticating and pressing `r` cannot leave a
+  previously failed source silently asleep.
+- **Concurrent persistence no longer loses a later update.** Same-target tabs
+  merge independently, and both cache and width writers adopt the merged disk
+  snapshot before their next save.
+- **Selections stay attached to visible items as lists change.** Insertions
+  above a row reconcile the viewport without opening a different item; a missing
+  item clears selection instead of selecting a replacement.
+- **Quitting aborts in-flight `gh ... view --web` children.** The app no longer
+  waits for a stalled browser-open command after terminal teardown begins.
+- **Row failures reset only when row content changes.** Unchanged parent renders
+  no longer clear an error boundary, while corrected data can recover in place.
+- **Status hints now describe only controls that can act.** Empty lists do not
+  advertise movement or opening, compact layouts do not advertise width mode,
+  and Security does not advertise an unsupported open action.
 ## [0.8.0] - 2026-08-11
 ### Added
@@ -647,7 +734,10 @@ 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.8.0...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
 [0.7.0]: https://github.com/juan294/gh-glance/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/juan294/gh-glance/releases/tag/v0.6.1

package/README.md CHANGED Viewed

@@ -11,38 +11,43 @@
 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.8.0
+[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. Three more markers appear when they
+> 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
 > limit, a `!` after the Actions count means the newest run failed — so "is CI
-> red" is answerable without switching to that tab — and a `?` in place of the
-> Security count means its endpoints could not be read, which is not the same
-> as there being nothing to report.
+> red" is answerable without switching to that tab — an `x` means the tab's
+> latest fetch failed, and a `?` in place of the Security count means its
+> endpoints could not be read, which is not the same as there being nothing to
+> report.
 <!-- contract:allow-emoji -- the check/cross above stand in for Nerd Font
      Octicons the app actually draws; they are literal examples, not decoration. -->
@@ -64,23 +69,27 @@ current.
 - **Issues** -- open issues: title, author, first label, age
 - **Pull Requests** -- open PRs: title, author, branch, review status
   (approved / changes requested / pending), age
-- **Security** -- open Dependabot alerts: package, summary, age, sorted with the
-  most severe first and with severity spelled out in its own column, not carried
-  by colour alone. One page of 100 newest alerts is fetched and ranked, so on a
-  repository with more open alerts than that the ranking covers the newest 100
-  rather than everything -- the `+` marker on the count is what tells you.
-  Code scanning and secret scanning alerts are included too, on repos/plans
-  that have GitHub Advanced Security enabled -- see [Limitations](#limitations).
+- **Security** -- open Dependabot, code-scanning, and secret-scanning alerts,
+  sorted with the most severe first and with severity spelled out rather than
+  carried by colour alone. Each source starts with its newest 100 open alerts.
+  When that page is full, Dependabot and code scanning also fetch bounded
+  critical/high priority lanes before merging and de-duplicating the result.
+  The `+` marker means at least one bounded lane filled, so the visible priority
+  set may still be incomplete. Code and secret scanning require GitHub Advanced
+  Security -- see [Limitations](#limitations).
 - Tab bar with live counts, pinned to the top of the pane above a divider,
   switchable via `1`-`4`, arrow keys, or `Tab`/`Shift+Tab`
 - Adjustable full-table columns, with visible header grips, a keyboard width
   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 on every refresh and animates during the
-  first load or while a workflow run is executing, so the pane says when it's
-  working without spending a line on it
-- 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
@@ -106,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
@@ -119,6 +128,10 @@ That is the whole install. `gh-glance` ships as a single `index.mjs` with no
 build step, so there is nothing to compile and nothing to configure -- the
 package is the source you can read in this repository.
+The installed package is a CLI, not a JavaScript library. The `gh-glance`
+executable is supported; package-root and deep imports are intentionally
+blocked so an internal test seam cannot become an accidental public API.
 Every published version is built and signed by GitHub Actions from a tagged
 commit on `main`, never from a maintainer's laptop, and carries [npm
 provenance](https://docs.npmjs.com/generating-provenance-statements) linking
@@ -234,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) |
@@ -263,14 +276,15 @@ line such as:
 Width: BRANCH 14  Tab select  <- -> resize  r reset  Esc done
 ```
-In an interactive terminal, you can also left-drag a visible `│` header grip.
-Pressing a grip selects its column and enters width mode; releasing the button,
-including outside the header, ends the drag. Row clicking, hover behavior, and
-pointer-shape changes are not supported. Mouse resizing has the same interactive
-terminal requirement as keyboard input.
+After pressing `w`, you can also left-drag a visible `│` header grip. Mouse
+reporting is enabled only while width mode owns the input, so a click outside
+that mode does not enter it. Releasing the button, including outside the header,
+ends the drag. Row clicking, hover behavior, and pointer-shape changes are not
+supported.
-While gh-glance is running, terminal-native text selection may require your
-terminal's mouse-reporting bypass modifier, commonly `Shift`.
+While width mode is active, terminal-native text selection may require your
+terminal's mouse-reporting bypass modifier, commonly `Shift`. Outside width
+mode, gh-glance leaves mouse reporting disabled.
 The cursor tracks the *item*, not the row position, so it stays on what you
 selected as new rows arrive above it. `Enter` works on Actions, Issues and Pull
@@ -303,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). |
@@ -314,14 +328,16 @@ 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`, `GH_ENTERPRISE_TOKEN`, `GH_CONFIG_DIR` | Not read by `gh-glance` -- passed through to `gh` untouched, along with the proxy variables. `gh-glance` handles no credentials of its own. Separate `GH_CONFIG_DIR` 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. The status icons carry text labels for it, but this path has not been tested against a real screen reader — treat it as unverified rather than supported. |
+| `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. |
 ### Saved column widths
@@ -358,11 +374,13 @@ $XDG_CONFIG_HOME/gh-glance/dashboard-cache.json
 ~/.config/gh-glance/dashboard-cache.json
 ```
-The cache is scoped to the repository and host being watched. In inferred mode,
-the host and current working directory form the identity, so rows from one
-checkout cannot appear in another. It retains at most five recent targets and
-60 rows per tab; a shortened cached tab keeps its `+` marker rather than
-presenting the saved count as complete.
+The cache is scoped to the repository, host, and effective `gh` account
+namespace. In inferred mode, the host and current working directory also form
+the identity, so rows from one checkout or credential context cannot appear in
+another. The namespace uses `GH_CONFIG_DIR`/`hosts.yml` identity plus one-way
+digests of supported token environment variables; raw credentials are never
+stored. It retains at most five recent targets and 60 rows per tab; a shortened
+cached tab keeps its `+` marker rather than presenting the saved count as exact.
 Only successfully parsed, non-blind observations replace saved rows. A failed
 request can add a live error or `?` marker, but it cannot turn known Security
@@ -371,7 +389,35 @@ unknown-version, or unwritable cache state is ignored rather than blocking the
 dashboard. On POSIX systems, gh-glance restricts its config directory to `0700`
 and the cache file to `0600`. The file contains repository data, including
 titles, authors, branches, and Security findings, but never GitHub credentials.
-It is recovery state owned by the UI, not a configuration interface.
+Both persistence files use a bounded advisory lock before atomic replacement.
+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
@@ -395,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
@@ -414,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 one probe per dashboard endpoint 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
@@ -443,34 +507,61 @@ 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 |
 |---|---|---|
-| Actions | ~1,620 | ~240 |
-| Issues or Pull Requests | ~300 | ~1,560 |
-| Security | ~2,280 | ~240 |
-Security is the most expensive, because it is three endpoints rather than one,
-and watching it costs just under half the REST budget. But Actions is not cheap
-either -- it is a third of the budget, and it is the tab every pane opens on,
-because one `gh run list` issues two REST requests rather than one. You do not
-have to take these figures on trust: `gh-glance --doctor` reports your actual
-remaining budget alongside what your configuration projects, which matters on a
-GitHub Enterprise tenant where the ceiling may not be 5,000 at all.
-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.
+| Actions | up to ~1,800 | ~240 |
+| Issues or Pull Requests | up to ~480 | ~1,560 |
+| Security | ~2,280 normally; up to ~4,440 | ~240 |
+Security is the most expensive. A repository whose newest alert pages are not
+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
+this projection beside the server's actual REST and GraphQL budgets. Enterprise
+ceilings can differ from 5,000.
+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
@@ -479,22 +570,19 @@ 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
 - **Security tab**: code scanning and secret scanning alerts require [GitHub
   Advanced Security](https://docs.github.com/en/code-security/getting-started/github-security-features).
   On repos/plans without it, `gh-glance` doesn't crash or spam errors -- it
@@ -526,12 +614,13 @@ a single pane on a healthy budget stays at 5 seconds and shows no badge.
   has its own breakpoint and drops to bare keys (`↑↓ Ent r q`) rather than
   truncating.
 - **Mouse reporting lifecycle.** Interactive sessions enable terminal mouse
-  reporting for header drags and disable it before handing the terminal back.
-  See [Adjusting column widths](#adjusting-column-widths) for text-selection
-  behavior while it is active.
-- Issues and pull requests are fetched 150 at a time and alerts 100 at a time.
-  A count is shown as `n+` when it was truncated, so the number is never
-  presented as exact when it is not.
+  reporting only after `w` enters width mode, and disable it when that mode or
+  the app exits. See [Adjusting column widths](#adjusting-column-widths) for
+  text-selection behavior while it is active.
+- Issues and pull requests are fetched 150 at a time. Each Security source has
+  a newest-100 lane; full Dependabot and code-scanning pages activate bounded
+  priority lanes. A count is shown as `n+` when any lane fills, so the number is
+  never presented as exact when it is not.
 - The Actions **TIME** column measures from the run's start to its last update.
   `gh` exposes no completion timestamp, so a workflow that was re-run later
   reports the span up to the re-run rather than its original duration.
@@ -545,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
@@ -571,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. |