gh-glance 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,115 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-06
+
+### Changed
+
+- **Upgrading requires restarting older panes, and may wait for a quota reset.**
+  The coordination protocol moved from version 3 to 5. A pane still running an
+  older build holds a lease this one refuses to coordinate against, so it must
+  be closed; if that pane left API charges it never settled, admission waits for
+  the affected quota window to reset before spending against a counter it cannot
+  account for. Both are conservative on purpose, and both clear on their own.
+- **A slow or failed budget observer no longer holds up the other resource.**
+  Core and GraphQL are claimed, published and retried independently. What still
+  couples them is the shared transport permit and any account-wide hold, which
+  are enforced where they belong.
+
+### Added
+
+- **Secondary rate limits back off on a bounded ladder.** A `Retry-After` the
+  server supplies is honoured exactly, in seconds or as an HTTP date, and
+  concurrent holds merge by maximum so a shorter error cannot shorten a longer
+  hold. Without a supplied deadline the client waits 60, 120, 240, 480 then 900
+  seconds by consecutive throttle; that cap applies only to the delay gh-glance
+  chooses, never to one the server asked for. After five consecutive throttles
+  it stops choosing and waits for an explicit refresh.
+- **A run of manual refreshes yields a turn to a waiting tab.** Manual work
+  still outranks background polling, but after three consecutive grants an
+  active tab that has been waiting goes next, so holding `r` can no longer
+  starve the rest of the dashboard.
+
+### Fixed
+
+- **A permission error no longer pauses every pane.** A 403 carrying no
+  rate-limit headers and no secondary-limit marker is a permission failure, not
+  a throttle. It previously held the shared transport, so one repository the
+  token could not read stalled every pane using that account.
+- **The external-use estimator can come back down.** When other clients were
+  busy, gh-glance would raise its estimate of their share and then keep pacing
+  against it: each sampling window closed on publication even when the sample
+  was too small to reconcile, discarding the local accumulation that would
+  eventually have made one. A window now closes only when it actually
+  reconciles, and a new quota window starts from no assumed external use rather
+  than inheriting the previous window's ratio.
+- **A request that cost nothing no longer paces as though it had.** Work is
+  paced by the cost it reserves, which is a worst case. A conditional request
+  answered `304` spends nothing, and cancelled work spends nothing at all -- the
+  unused pacing is now returned instead of leaving the next request waiting out
+  a slot nobody used.
+- **Older coordination files are readable again.** The version 3 to 4 change
+  altered the file's shape, and the legacy reader recognised only the version
+  number, so every file an older pane had actually written was rejected as
+  corrupt -- exactly the file the restart boundary has to read to see that an
+  older pane is still running.
+
+## [0.12.0] - 2026-09-06
+
+### Added
+
+- **Panes sharing a GitHub account now share one API budget.** Quota is keyed by
+  the verified principal and access by the effective credential, so two tokens
+  for the same account coordinate as one instead of splitting the budget in
+  half. A shared transport permit serializes HTTP starts across panes, and the
+  bootstrap allowance is persisted before a request starts, so a crash, restart
+  or manual refresh cannot replenish it.
+
+### Changed
+
+- **Issues and Pull Requests use explicit, bounded GraphQL documents.**
+  `gh issue list` and `gh pr list` silently routed through GraphQL at a price
+  nothing in the codebase could name -- the budget was debited from a number
+  measured by hand once and written into a constant. Both now use fixed,
+  versioned documents with typed variables on stdin, so the query never reaches
+  argv and every page declares the cost it is held to.
+- **`gh api rate_limit` is no longer a source of spendable GraphQL capacity.**
+  A claimed observer that selects only the meter supplies capacity and reports
+  what it cost. `/rate_limit` remains a diagnostic, is labelled as one in
+  `--doctor`, and is dropped on migration rather than kept as spendable
+  evidence.
+- **Opening a row spends no API budget.** `gh <kind> view --web` paid a request
+  to be told a URL the app already held, and had to refuse the user the page
+  when the budget was tight. URLs are admitted -- https only, matching host --
+  before reaching the platform opener.
+
+### Fixed
+
+- **Issues and Pull Requests worked only with an explicit `--repo`.** `gh`
+  infers the repository from the working directory and GraphQL cannot, so the
+  query variables went out half-filled without it.
+- **Multi-page repositories leaked a tab reservation on every poll.** Settlement
+  summed all page costs even though later pages settle against their own
+  reservation, and the resulting over-settlement was rejected as corrupt --
+  discarding the budget observations from the only requests carrying real cost
+  evidence.
+- **The budget observer's own spend was attributed to external consumers**, so
+  the governor progressively throttled real work to make room for its own
+  probing.
+- **A contended registry lock could retract a verified identity**, blanking
+  every tab and discarding the ETags that make the next round cheap. Unknown
+  and changed are now distinct, and only a proven change discards rows.
+- **Bootstrap attempts that never proved a principal were never retired**, so
+  the registry filled to its cap behind a captive portal and refused every
+  later bootstrap permanently, recoverable only by deleting state by hand.
+- **Identity debt transfer wrote the ledger and registry non-atomically**, so a
+  crash could orphan a charged receipt or record a debt as transferred to a
+  ledger that never received it.
+- **A stopped pane held the single machine-wide HTTP permit indefinitely**, as
+  it was reclaimed only on owner death.
+- **The Open key hint was dead on every tab**, and opening a cache-hydrated row
+  did nothing because the cache dropped the row's URL.
+
 ## [0.11.2] - 2026-08-31
 
 ### Fixed
@@ -795,7 +904,9 @@ 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.11.2...HEAD
+[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/juan294/gh-glance/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/juan294/gh-glance/compare/v0.11.2...v0.12.0
 [0.11.2]: https://github.com/juan294/gh-glance/compare/v0.11.1...v0.11.2
 [0.11.1]: https://github.com/juan294/gh-glance/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/juan294/gh-glance/compare/v0.10.0...v0.11.0

package/README.md

@@ -319,7 +319,7 @@ pane definition. Flags are there when you want them:
 | `-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>` | 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`. |
+| `--verbose` | Log one line per dashboard `gh` call to stderr, with timing and outcome. Credential lookup and the account-identity proof are deliberately excluded, so that they cannot log anything derived from a token. stderr must be redirected: `gh-glance --verbose 2>gh-glance.log`. |
 | `--doctor` | Print a diagnostic report and exit. See [Diagnostics](#diagnostics). |
 
 An unrecognised flag exits 2 rather than being ignored, so a typo fails loudly.
@@ -396,21 +396,39 @@ recovery state owned by the UI, not a configuration interface.
 
 ### Private API governor state
 
-API admission uses a separate file beside the cache:
+API admission uses a separate directory 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
+$XDG_CONFIG_HOME/gh-glance/coordination-v2/
+~/Library/Application Support/gh-glance/coordination-v2/
+~/.config/gh-glance/coordination-v2/
 ```
 
-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.
+It holds `registry.json`, which maps credentials to verified accounts, and one
+`quota-<hash>.json` ledger per account. The ledger hash binds the effective
+GitHub host to the *verified principal* -- the account kind and numeric ID that
+GitHub itself confirmed -- rather than to whichever local `gh` configuration
+happened to select it, so two tokens for the same account coordinate as one
+instead of splitting the budget in half.
+
+A ledger 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.
+
+`registry.json` is the one exception, and it is deliberate: to know that two
+credentials are the same account it stores that account's numeric ID and its
+sanitized login, alongside private digests of the credentials themselves. No
+token is ever written, to it or anywhere else. Ephemeral lock records contain
+only a PID and random nonce.
+
+Panes from an older release coordinate through the previous
+`rate-governor-v1-<scope hash>.json` files, which this version cannot join.
+It preserves them as evidence, refuses to activate while any of their leases is
+still live, and waits out any unsettled charge they left behind. Closing the
+older panes is what completes the upgrade -- gh-glance will not close them for
+you, and deleting the files instead discards quota that is still owed.
 
 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
@@ -692,7 +710,12 @@ GH_GLANCE_ICONS=ascii gh-glance
 | 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. |
+| `Restart required: close older gh-glance panes` | A pane from an older release still holds a live lease in the previous coordination format, which this version cannot join. Quit those panes; this one resumes on its own. Nothing is killed for you, and no state needs deleting. |
+| `Upgrade waiting for legacy quota reset` | The older panes are gone, but left spend that cannot be proven settled. It waits for the affected rate-limit window to reset rather than assume the quota is free. |
+| `Coordination state unavailable; evidence preserved` | Coordination state could not be read and was deliberately not overwritten, so nothing is lost. Run `gh-glance --doctor` and check the config directory's permissions. |
+| `Shared HTTP request or cooldown in progress` | Panes share one outbound request slot and one cooldown. Another pane holds it, or a server-sent `Retry-After` is still running. Normal pacing, not an error. |
+| `Verified identity unavailable; waiting to retry` | The account behind your credential has not been confirmed yet -- not signed in, a denied or malformed proof, or a slow credential helper. Check `gh auth status`. Retries are rate-limited, so this clears on its own rather than immediately. |
+| It stopped updating and you cannot tell why | Run `gh-glance --verbose 2>gh-glance.log`, reproduce, then read the log: one line per dashboard `gh` call with its duration and outcome. Credential lookup and the identity proof are excluded by design. 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. |
 
 ## Contributing