gh-glance 0.16.2 → 0.17.1

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] - 2026-10-26
+
+### Fixed
+
+- A full debt-group journal no longer pins every pane of an account behind
+  "Local coordination accounting overflow". Quiescent groups now merge once the
+  journal is half full, after any active probe finishes or expires, so the
+  journal can free space for retiring a control receipt. Ledgers already wedged
+  in this state recover automatically after upgrading.
+- Pasted or multi-character input such as `12` is ignored instead of being read
+  as a tab number. Single-digit tab keys are unchanged.
+- Webhook events now match configured targets whose repository name differs in
+  case from the name GitHub sends, including access-removal events that fence
+  cached data. Ambiguity across hosts is still rejected.
+- A collector view with an old snapshot shows `Stale` or `Cached` with its
+  source age. It shows `Disconnected`, still with that age, only when the
+  collector connection or its app authorization is lost.
+
+### Changed
+
+- Updated React to 19.3.0 and refreshed existing tooling/action versions.
+  Patched the development-only brace-expansion and Zod vulnerabilities.
+- README: Homebrew installation (`brew install juan294/tap/gh-glance`) is
+  documented, with a note to use one installation method.
+- Development CI monitoring uses Sutura v0.4.0.
+- A journal that is genuinely full of unsettled requests reports "Local
+  coordination journal is full" with an automatic retry instead of the hard
+  accounting-overflow notice.
+- `gh-glance --doctor` reports debt-journal occupancy as `debt groups`, and
+  for a hard coordination failure, including a ledger that is missing or
+  unreadable, names the state file and the `repair`: quit every pane, move the
+  ledger, its recovery journal and `registry.json` aside, relaunch.
+
+## [0.17.0] - 2026-10-25
+
+### Added
+
+- Contextual, paginated help with the selected GitHub host and repository,
+  complete diagnostics and recovery actions, including in narrow terminals.
+- Optional Actions setup checks with `s` in standalone mode: one read-only
+  request lists up to 100 workflows, reports incomplete coverage and keeps a
+  separate result for five minutes. Press `g` to open the repository's Actions
+  page, including from collector and SSH views.
+
+### Changed
+
+- Empty tabs explain what was checked, what the result means and what to do
+  next. Saved views, waiting, overdue data and failed refreshes retain their
+  actual source-check context.
+- README: the provenance note now says the published package is the exact
+  tarball tested for the release pull request.
+- Development CI monitoring uses Sutura v0.3.9 with a repository-scoped App token.
+
+### Fixed
+
+- Preserve actionable login and local-storage remedies in short terminal panes.
+- Distinguish partial or disabled Security coverage from an all-clear result,
+  and disclose uncertain check times without inventing freshness.
+- Keep setup and browser failures separate from workflow-run results, with
+  bounded retries, shared rate-limit accounting and account-change fencing.
+
 ## [0.16.2] - 2026-10-03
 
 No change to the dashboard itself: `index.mjs` is identical to 0.16.1. This
@@ -1254,7 +1315,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.16.2...HEAD
+[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.17.1...HEAD
+[0.17.1]: https://github.com/juan294/gh-glance/compare/v0.17.0...v0.17.1
+[0.17.0]: https://github.com/juan294/gh-glance/compare/v0.16.2...v0.17.0
 [0.16.2]: https://github.com/juan294/gh-glance/compare/v0.16.1...v0.16.2
 [0.16.1]: https://github.com/juan294/gh-glance/compare/v0.16.0...v0.16.1
 [0.16.0]: https://github.com/juan294/gh-glance/compare/v0.15.2...v0.16.0

package/README.md

@@ -25,14 +25,14 @@ without switching to the browser.
 ╭─ Actions · owner/repo ──────────────────────────────────────────────────╮
 │     TITLE                  │WORKFLOW  │BRANCH        │TIME   │UPDATED   │
 │ ─────────────────────────────────────────────────────────────────────── │
-│ >+  ci: pin actions to com… #443 CI    develop        1m20s   44d ago   │
-│  x  fix: restore the prima… #442 Code… develop        1m28s   44d ago   │
-│  +  chore: bump dependenci… #441 CI    dependa…int-10 30s     44d ago   │
-│  -  docs: update the readme #440 CI    develop        15s     45d ago   │
+│ >+  ci: pin actions to com… #443 CI    develop        1m20s   85d ago   │
+│  x  fix: restore the prima… #442 Code… develop        1m28s   85d ago   │
+│  +  chore: bump dependenci… #441 CI    dependa…int-10 30s     85d ago   │
+│  -  docs: update the readme #440 CI    develop        15s     86d ago   │
 │                                                                         │
 │                                                                         │
 ╰──────────────────────────────────────────────────────────────── 4 of 4 ─╯
-· Watching               Refresh: r Quit: q Move: ↑↓ Open: Ent Width: w
+· Watching               Refresh: r Quit: q Help: ? Move: ↑↓ Open: Ent w
 ```
 
 > Generated from this candidate's real binary under the repository PTY harness
@@ -121,10 +121,28 @@ current.
 
 ## Install
 
+With Homebrew on macOS or Linux:
+
+```bash
+brew install juan294/tap/gh-glance
+```
+
+Future updates use your normal `brew upgrade`. The
+[Homebrew tap](https://github.com/juan294/homebrew-tap) follows published npm
+releases automatically and supplies its own Node runtime. If moving from npm,
+remove existing npm copies first; the tap README includes migration commands.
+Restart running dashboard panes after upgrading.
+
+Alternatively, install with npm (Node.js 22 or newer):
+
 ```bash
 npm install -g gh-glance
 ```
 
+Use one installation method. NVM keeps global npm packages separate for each
+Node installation, so an npm update may not affect a copy launched from another
+prefix.
+
 That is the whole install for the default standalone dashboard. `gh-glance`
 ships as a single `index.mjs` with no build step, so there is nothing to
 compile. The optional collector, SSH, webhook, and GitHub App modes use the
@@ -134,15 +152,20 @@ 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
+Every published version is the exact tarball GitHub Actions packed and tested
+for the release pull request, published 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
-the tarball back to the workflow run and commit that produced it. The
+the tarball back to the workflow run and commit that published it. The
 "Provenance" section on the [package
 page](https://www.npmjs.com/package/gh-glance) shows the exact source.
 
 ### First run
 
+The footer keeps `?` available for contextual help, even in a narrow pane.
+Help explains the selected repository and host, the current observation, and
+what to do next; its pages keep long targets and recovery details reachable.
+
 The default standalone dashboard uses the credentials and active account
 already selected by your local `gh` CLI. It does not persist or display the
 token. Check that account before starting the dashboard:
@@ -176,6 +199,33 @@ the core gh-glance minimum remains unchanged. To keep simultaneous panes on
 different accounts, use separate `GH_CONFIG_DIR` values as described under
 [No account pinning](#limitations).
 
+A successful empty result is different from a check that has not succeeded.
+Actions says “No workflow runs found” and explains that runs come from workflows
+with matching triggers. Issues and Pull requests report open items. Security
+reports only the sources it could check and keeps unavailable-source notes visible.
+An empty result is not a repository-wide health or security clearance.
+
+On Actions, press `s` for an optional read-only setup check or `g` to open the
+selected repository's Actions page. The setup check lists at most 100 workflows
+in one request. It reports partial coverage and unfamiliar states explicitly;
+zero workflows or an access error does not prove that Actions is disabled.
+Setup results have their own check time and do not change the run list or its
+freshness. A successful or partial result is reused for five minutes. Failures
+keep the prior dated result and require `s` to retry after at least 30 seconds
+and any shared API hold. There is no automatic setup retry. Setup checks are
+available only in standalone mode; connected collector and SSH views offer `g`
+instead. Neither key creates, enables, edits, or dispatches a workflow.
+
+“Checking” and “Waiting to check” mean no successful result is available yet.
+A failed load shows the actual recovery action. A failed refresh keeps the prior
+result and its original check time. “Needs an update” describes overdue data;
+it does not by itself mean a network request failed. Unknown or future source
+clocks show “Last-check time unavailable”.
+
+With the default on-demand policy, Issues, Pull requests and Security show a
+saved view between checks. Press `r` to check again; opening the tab also follows
+the normal refresh policy. These tabs do not promise continuous polling.
+
 ### From a clone
 
 For hacking on it, or to run an unreleased revision:
@@ -251,8 +301,10 @@ stdout isn't a terminal rather than streaming redraw frames into a pipe.
 | `Enter` | Open the selected item, or accept an onboarding prompt |
 | `r` | Request a current-tab refresh. It sends the cached validators, so an unchanged tab answers `304` and spends nothing. A safe grant is still required. |
 | `R` | Resynchronize the current tab: one generation without validators, and the only key that clears a negative capability backoff. Still subject to the budget and the secondary cooldown. |
+| `s` | On Actions, request or reuse a read-only setup check (standalone only) |
+| `g` | On Actions, open the selected repository’s Actions page |
 | `w` | Adjust table column widths |
-| `?` | Show the keys without leaving the dashboard (any key closes it) |
+| `?` | Open or close contextual help; `n` / `p` moves through its pages |
 | `q` / `Esc` / `Ctrl+C` | Quit (`Esc` leaves width mode) |
 
 ### Adjusting column widths
@@ -304,9 +356,16 @@ switch `gh` into non-interactive mode and require choosing a visibility in
 advance. Press `q` or `Esc` to decline. To watch an existing repository without
 attaching this folder, restart with `gh-glance --repo owner/name`.
 
-When the repository was chosen explicitly, with `--repo` or `GH_REPO`, the panel
-says so: `╭─ Actions · acme/widget ─`. That is what tells two side-by-side panes
-apart. It is dropped before the tab name when the pane is too narrow for both.
+The panel names the selected repository, including targets inferred from Git
+remotes: `╭─ Actions · acme/widget ─`. Non-default hosts are included in the
+target. Selection does not prove that the active account can access it. When
+the pane is too narrow for the target, press `?` to read its complete name and
+host, the current check state, source time, recovery action, and key reference.
+
+Help wraps long text and uses `n` / `p` for next / previous page. `?` closes it;
+any other ordinary key closes help without performing that key's usual action.
+`q`, `Esc`, and `Ctrl+C` still quit. Width mode keeps its own keys: leave it
+before opening help.
 
 If `gh-glance` is started without an interactive stdin (for example with stdin
 redirected), the key handlers cannot run and the status bar shows only `Quit: ^C`
@@ -724,11 +783,14 @@ and the lock path separately. A readable metadata file does not make an aged
 orphan lock or invalid snapshot healthy; plain doctor never repairs either.
 When one cached identity names the selected host, plain doctor also reads its
 quota ledger without changing it or contacting GitHub. It reports receipt and
-debt totals, observer age, the current recovery cause, and an actual retry time
-when one is known. If several cached identities match, it says the scope is
-unavailable instead of choosing an account. For a corrupt or unreadable quota
+debt totals, debt-group occupancy (`debt groups`), observer age, the current
+recovery cause, and an actual retry time when one is known. If several cached
+identities match, it says the scope is unavailable instead of choosing an
+account. For a corrupt or unreadable quota
 file, it names the coordination directory and a `quota-[redacted].json` file
-pattern with the cause. The private quota fingerprint stays out of reports.
+pattern with the cause. For a hard coordination failure it also prints a
+`repair` line with the manual steps. The private quota fingerprint stays out of
+reports.
 
 Use `gh-glance --doctor --probe` when live capability evidence is needed. Probe
 mode uses an ephemeral governor lease and admits every quota-consuming endpoint
@@ -1082,7 +1144,8 @@ GH_GLANCE_ICONS=ascii gh-glance
 | `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. This one has a deadline and clears itself. |
 | `Upgrade blocked: older spend cannot be settled or waited out` | Older spend has no reliable reset or child evidence. Verify old children ended and use `gh-glance --doctor` to inspect reserved units. An unidentifiable old child may require a verified system restart before a later observer can retire its charge. Keep the quota files as accounting evidence. |
 | `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. |
-| `Local coordination` corruption, overflow, full storage, or unsafe permissions | Run `gh-glance --doctor`; its read-only report gives the exact cause and redacted local file location when known. Repair storage or permissions, then let the app retry. Preserve corrupt and overflow evidence for diagnosis. |
+| `Local coordination journal is full` | Every slot for unsettled or recently settled requests is in use. The app retries by itself, and older requests settle after about an hour. Nothing needs repair. `gh-glance --doctor` shows the occupancy as `debt groups`. |
+| `Local coordination` corruption, overflow, full storage, or unsafe permissions | Run `gh-glance --doctor`; its read-only report gives the exact cause and redacted local file location when known. For a hard failure it also prints a `repair` line: quit every pane, move the state file, its `.recovery.json` and `registry.json` aside, then relaunch. Otherwise repair storage or permissions and let the app retry. Preserve corrupt and overflow evidence for diagnosis. |
 | `Saving request result` or `Recovering interrupted request` | The original request may have consumed quota. The app keeps its charge, retries settlement without repeating HTTP, and waits for safe observer evidence before retiring uncertain debt. |
 | `GitHub request limit` | A shared secondary hold preserves GitHub's retry deadline. Wait for the shown time; if the repeated-limit circuit explicitly asks, press `r` once to retry. Repeated refresh cannot bypass a hold. |
 | `Collector connection unavailable` or `GitHub App authorization unavailable` | Restore the selected collector connection or App authorization. The mode does not switch to independent requests. Cached rows remain labeled with their source age. |