gh-glance 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.6.0] - 2026-08-06
+
+### Added
+
+- **An interactive missing-remote onboarding prompt.** Starting gh-glance in a
+  local repository with no remotes now offers to hand off to the user-confirmed
+  interactive `gh repo create` flow, while keeping quit and explicit `--repo`
+  paths visible. Declining the prompt makes no repository change.
+- **Failure-triggered account and repository context.** After an ambiguous
+  repository-access failure, gh-glance performs read-only active-account and
+  repository checks through `gh`, and `--doctor` now includes a `Repository
+  access` probe.
+
+### Fixed
+
+- **Clean no-login failures now explain the delegated authentication path.**
+  Previously these were unclassified raw `gh` errors. They now direct the user
+  to login or authorization evidence through their own `gh` configuration and
+  remain retryable.
+- **Inaccessible repository errors now converge on honest wording.** Actions'
+  REST 404 and Issues' GraphQL repository-resolution failure described the same
+  inaccessible target through unrelated messages. List tabs now say “not found
+  or inaccessible” without claiming whether the target is missing or private.
+
+## [0.5.1] - 2026-08-04
+
+### Changed
+
+- **The blank-icons hint waits for a start that is actually stuck.** It shipped
+  in 0.5.0 on the loading line unconditionally, so every start put a line naming
+  an environment variable in front of everyone for the second or two the first
+  fetch takes -- a dim `loading actions…` reads as "working", the same line with
+  a remedy attached reads as a warning about a problem you do not have. It now
+  appears only once a first fetch has been running 3s, which is past the slow end
+  of what `gh run list` costs on the tab you land on (measured: 1.4-3.0s after
+  the first frame, against 0.6-1.1s for the other three tabs). An ordinary start
+  never shows it; a pane of blank boxes that is genuinely waiting still explains
+  itself.
+
 ## [0.5.0] - 2026-08-04
 
 Findings from a cross-functional audit, filtered hard: everything that would
@@ -516,6 +557,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.
 
+[0.6.0]: https://github.com/juan294/gh-glance/releases/tag/v0.6.0
+[0.5.1]: https://github.com/juan294/gh-glance/releases/tag/v0.5.1
 [0.5.0]: https://github.com/juan294/gh-glance/releases/tag/v0.5.0
 [0.4.1]: https://github.com/juan294/gh-glance/releases/tag/v0.4.1
 [0.4.0]: https://github.com/juan294/gh-glance/releases/tag/v0.4.0

package/README.md

@@ -121,6 +121,41 @@ the tarball back to the workflow run and commit that produced it. The
 "Provenance" section on the [package
 page](https://www.npmjs.com/package/gh-glance) shows the exact source.
 
+### First run
+
+`gh-glance` uses the credentials and active account already selected by your
+local `gh` CLI. It does not request, inspect, or store the token itself. Check
+that account before starting the dashboard:
+
+```bash
+gh auth status
+
+# Only when no account is active:
+gh auth login
+
+gh-glance
+```
+
+Cloning over SSH or HTTPS and authenticating `gh` are separate credential
+paths, so a successful clone does not prove that the active `gh` account can
+access the repository through the API. For a non-default host, authenticate it
+explicitly with `gh auth login --hostname <host>`.
+
+If several accounts are authenticated on the same host, inspect and select the
+one you intend to use:
+
+```bash
+gh auth status
+gh auth switch --hostname github.com --user <login>
+```
+
+`gh auth switch` is an explicit user command, not a gh-glance action. It changes
+the active account globally for that `gh` configuration. If `gh auth switch
+--help` is unavailable, update `gh` to use this optional multi-account workflow;
+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).
+
 ### From a clone
 
 For hacking on it, or to run an unreleased revision:
@@ -193,7 +228,7 @@ stdout isn't a terminal rather than streaming redraw frames into a pipe.
 | `Tab` / `Shift+Tab` | Next / previous tab |
 | `↑` / `↓` or `j` / `k` | Move the cursor between rows |
 | `PgUp` / `PgDn` | Move a page at a time |
-| `Enter` | Open the selected item in your browser |
+| `Enter` | Open the selected item, or accept an onboarding prompt |
 | `r` | Refresh the current tab now |
 | `?` | Show the keys without leaving the dashboard (any key closes it) |
 | `q` / `Esc` / `Ctrl+C` | Quit |
@@ -205,6 +240,14 @@ itself after 60s with no cursor movement, so a pane left idle in the corner of
 a screen doesn't sit there marked forever -- and the next arrow key picks up
 from what is on screen rather than jumping back to the top of the list.
 
+If the current local repository has no GitHub remote, gh-glance shows a setup
+prompt instead of raw `gh` stderr. Press `Enter` to leave the dashboard and run
+the interactive `gh repo create` flow, then choose **Push an existing local
+repository**. Plain `gh repo create` is intentional: adding `--source` would
+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.
@@ -234,7 +277,7 @@ Environment variables work too, and the flags take precedence:
 |---|---|
 | `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 |
+| `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_ICONS=unicode` | Plain ASCII status icons, for terminals without a Nerd Font |
 | `GH_GLANCE_NO_ANIMATION=1` | Freeze the spinner — no motion at all |
 | `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 |
@@ -282,9 +325,15 @@ 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; and one probe per
-endpoint with the exact argv it sent, its outcome, and how any error was
-classified (`unavailable`, `rate-limited`, `auth-problem` or `other`).
+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`).
+
+The `Repository access` probe shows whether the target resolves for the active
+`gh` credentials. A failed GitHub resolution response cannot distinguish a
+nonexistent, renamed, or stale target from a private repository hidden from
+that identity.
 
 Add `--verbose` to get a log of every `gh` call it makes alongside the report.
 
@@ -401,6 +450,11 @@ in some terminals, which would shift every column to their right.
 |---|---|
 | `the gh CLI is not installed` | Install it from [cli.github.com](https://cli.github.com), then `gh auth login`. |
 | `not inside a git repository` | Run it from a cloned GitHub repository, or set `GH_REPO=owner/name`. |
+| `No GitHub remote found` | Press `Enter` to start `gh repo create`, then choose **Push an existing local repository**. Or press `q` and run `gh-glance --repo owner/name` to watch an existing repository without attaching this folder. |
+| `GitHub login or authorization required` | Run `gh auth status`. With no account, run `gh auth login`; with an expired authorization, run `gh auth refresh`; then press `r`. |
+| `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`. |
 | 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>`. |

package/index.mjs

@@ -22,7 +22,7 @@
 // disarmDevBuildLeak() for how that path is kept survivable rather than fatal.
 process.env.NODE_ENV ??= "production";
 
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -53,6 +53,23 @@ const REFRESH_MS = 5000;
 // last movement, not from tab switches or Enter) quietly drops it.
 const SELECTION_IDLE_MS = 60_000;
 
+// How long a first fetch has to still be unresolved before the loading line
+// offers the Nerd Font escape hatch. The hint used to be unconditional, which
+// put a line naming an environment variable in front of every user on every
+// start to catch the minority whose terminal cannot draw the glyphs -- a dim
+// "loading actions…" reads as "working", the same line with a remedy attached
+// reads as a warning, and it was on screen for the whole first fetch every time.
+//
+// The threshold is set from the fetch that actually gates it, not from a round
+// number: the hint hangs off the *visible* tab's loading line, and the tab you
+// land on is Actions, whose `gh run list` is by far the slowest call here
+// (measured against this repo: issues/PRs/alerts resolve 0.6-1.1s after the
+// first frame, runs 1.4-3.0s). 1.5s would have fired on most ordinary starts --
+// i.e. changed nothing. 3s sits past the slow end of that range, so a start that
+// reaches it is genuinely stuck rather than merely fetching, which is exactly
+// the moment the remedy is worth a line.
+const ICON_HINT_AFTER_MS = 3000;
+
 // `gh run list` costs roughly linearly in --limit (measured: ~1.2s at 20 runs,
 // ~3.0s at 100, ~4.9s at 150), so asking for a fixed 150 to render ~35 visible
 // rows was paying several seconds per refresh for rows nobody sees. Actions is
@@ -317,7 +334,11 @@ function errText(err) {
 // DNS, a 502) is a real failure that used to be reported as a confident,
 // plausible, and wrong claim that the feature was switched off.
 function isUnavailable(err) {
-  return /HTTP (403|404)/.test(errText(err));
+  const text = errText(err);
+  return (
+    /HTTP (403|404)/.test(text) ||
+    /Could not resolve to a Repository with the name .* \(repository\)/i.test(text)
+  );
 }
 
 function isRateLimited(err) {
@@ -342,12 +363,20 @@ function isRateLimited(err) {
 // entirely in the positive. It stays clear of the genuine not-enabled messages,
 // which talk about features rather than access.
 const AUTH_MARKERS =
-  /SAML|single[- ]sign[- ]on|\bSSO\b|must grant|not authoriz|unauthoriz|access restriction|Bad credentials|requires authentication|re-?authoriz|token .*scope|missing .*scope|insufficient/i;
+  /SAML|single[- ]sign[- ]on|\bSSO\b|must grant|not authoriz|unauthoriz|access restriction|Bad credentials|requires authentication|re-?authoriz|token .*scope|missing .*scope|insufficient|not logged into any GitHub hosts|To get started with GitHub CLI|run: gh auth login|none of the git remotes[\s\S]*known GitHub host/i;
 
 function isAuthProblem(err) {
   return AUTH_MARKERS.test(errText(err));
 }
 
+// A local repository with no remote is an onboarding state, not an API or
+// authentication failure. Both strings are emitted by current gh commands:
+// list commands include the "failed to determine base repo" prefix, while
+// `gh repo view` returns the shorter form.
+function isMissingRemote(err) {
+  return /(?:failed to determine base repo:\s*)?no git remotes found/i.test(errText(err));
+}
+
 // The one place the three predicates are turned into a verdict. Both consumers
 // go through it -- the fetcher, to choose a note and a backoff ladder, and
 // `--doctor`, to report what gh-glance concluded -- so the report cannot claim
@@ -363,6 +392,7 @@ function isAuthProblem(err) {
 // repository's configuration.
 function classify(err) {
   if (err == null) return "ok";
+  if (isMissingRemote(err)) return "no-remote";
   if (isRateLimited(err)) return "rate-limited";
   if (isAuthProblem(err)) return "auth-problem";
   if (isUnavailable(err)) return "unavailable";
@@ -384,11 +414,77 @@ function classify(err) {
 // positive that only picked a retry ladder was cheap, whereas one that also
 // rewrites the on-screen text turns into a confidently wrong instruction.
 const VERDICT_REMEDY = {
-  "auth-problem": "GitHub authorization failed -- try `gh auth login` or `gh auth refresh`",
+  "no-remote":
+    "No GitHub remote found -- press Enter to create one, or use `gh-glance --repo owner/name`",
+  "auth-problem":
+    "GitHub login or authorization required -- run `gh auth status`, then `gh auth login` or `gh auth refresh`",
   "rate-limited": "GitHub rate limit reached -- backing off, this clears on its own",
-  unavailable: "not available for this repository",
+  unavailable:
+    "Repository not found or inaccessible to the active `gh` account -- check `gh auth status` and the repository target",
 };
 
+function toTabError(err) {
+  return { kind: "fetch", verdict: classify(err), raw: shortErr(err) };
+}
+
+function textTabError(err) {
+  return { kind: "text", text: shortErr(err) };
+}
+
+function failureTargetHost({ runtimeHost, ghHost, ghRepo, accounts } = {}) {
+  let ghRepoHost = null;
+  if (ghRepo) {
+    try {
+      ghRepoHost = parseRepoTarget(ghRepo).host;
+    } catch {
+      // GH_REPO is external process state, not validated argv. An invalid value
+      // is not evidence about which host an unavailable repository targeted.
+    }
+  }
+
+  const accountHosts = Array.isArray(accounts)
+    ? accounts
+        .map((account) => (typeof account?.host === "string" ? safe(account.host) : ""))
+        .filter(Boolean)
+    : [];
+  const distinctHosts = new Map(accountHosts.map((host) => [host.toLowerCase(), host]));
+  const soleAccountHost = distinctHosts.size === 1 ? distinctHosts.values().next().value : null;
+
+  return runtimeHost || ghHost || ghRepoHost || soleAccountHost || null;
+}
+
+function unavailableRemedy(accounts, targetHost) {
+  if (!Array.isArray(accounts) || !targetHost) return VERDICT_REMEDY.unavailable;
+  const normalizedTarget = String(targetHost).toLowerCase();
+  let matching = null;
+  for (const account of accounts) {
+    if (typeof account?.host !== "string" || typeof account?.login !== "string") continue;
+    const host = safe(account.host);
+    const login = safe(account.login);
+    if (!host || !login || host.toLowerCase() !== normalizedTarget) continue;
+    if (matching !== null) return VERDICT_REMEDY.unavailable;
+    matching = { host, login };
+  }
+  if (matching === null) return VERDICT_REMEDY.unavailable;
+
+  const { host, login } = matching;
+  const candidate = `Repository not found or inaccessible to ${login}@${host} -- check the target or run \`gh auth switch\``;
+  return candidate.length <= MAX_ERR_LENGTH ? candidate : VERDICT_REMEDY.unavailable;
+}
+
+function formatTabError(error, failureContext = null) {
+  if (error == null) return null;
+  if (error.kind === "text") return error.text;
+  if (error.verdict === "other") return error.raw;
+  if (error.verdict === "unavailable" && failureContext?.repo?.ok) {
+    return "not available for this repository";
+  }
+  if (error.verdict === "unavailable") {
+    return unavailableRemedy(failureContext?.accounts, failureContext?.targetHost);
+  }
+  return pick(VERDICT_REMEDY, error.verdict, null) ?? error.raw;
+}
+
 // Some pty wrappers (and a terminal mid-resize) report a size of 0 or
 // undefined. Taking that literally collapses the table to a single row (or
 // draws a zero-width border), so fall back to sane defaults until real
@@ -461,6 +557,7 @@ function logGh(args, startedAt, outcome) {
 // outside React entirely -- there is no component left to read a ref from. Kept
 // in this section, above every consumer, so nothing has to reach downward for it.
 let liveAbort = null;
+let setupChild = null;
 function registerLiveAbort(controller) {
   liveAbort = controller;
 }
@@ -469,6 +566,13 @@ function abortLiveRequests() {
   liveAbort = null;
 }
 
+function forwardSignalToChild(child, signal) {
+  // child.killed means only that kill() was called successfully; it becomes
+  // true before the process exits and therefore cannot gate SIGKILL escalation.
+  if (!child || child.exitCode !== null || child.signalCode !== null) return false;
+  return child.kill(signal);
+}
+
 async function runGh(args, { signal } = {}) {
   const startedAt = Date.now();
   try {
@@ -525,6 +629,146 @@ function apiPath(path) {
 // inline, because `--doctor` reports these vectors and a second copy of them
 // would be a report that drifts away from what the dashboard actually sends --
 // which is the failure mode the whole diagnostics command exists to rule out.
+function repoContextArgs() {
+  const target = runtime.repo ? qualifiedRepo() : null;
+  return [
+    "repo",
+    "view",
+    ...(target ? [target] : []),
+    "--json",
+    "nameWithOwner,url,viewerPermission",
+  ];
+}
+
+function authContextArgs() {
+  return [
+    "auth",
+    "status",
+    "--active",
+    "--json",
+    "hosts",
+    "--jq",
+    ".hosts | to_entries | map(.key as $host | .value[] | select(.active == true) | {host: $host, login: .login})",
+  ];
+}
+
+function parseRepoContext(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (
+      value == null ||
+      Array.isArray(value) ||
+      typeof value !== "object" ||
+      typeof value.nameWithOwner !== "string" ||
+      typeof value.url !== "string" ||
+      typeof value.viewerPermission !== "string"
+    ) {
+      return null;
+    }
+    return {
+      ok: true,
+      nameWithOwner: safe(value.nameWithOwner),
+      url: safe(value.url),
+      viewerPermission: safe(value.viewerPermission),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseAuthContext(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (!Array.isArray(value)) return null;
+    return value
+      .filter(
+        (row) =>
+          row != null &&
+          !Array.isArray(row) &&
+          typeof row === "object" &&
+          typeof row.host === "string" &&
+          typeof row.login === "string",
+      )
+      .map((row) => ({ host: safe(row.host), login: safe(row.login) }));
+  } catch {
+    return null;
+  }
+}
+
+function failedContext(err) {
+  return { ok: false, verdict: classify(err), raw: shortErr(err) };
+}
+
+function missingFailureContext() {
+  return {
+    repo: { ok: false, verdict: "other", raw: "Repository context unavailable" },
+    accounts: null,
+  };
+}
+
+function buildFailureContext(repoSettlement, authSettlement) {
+  const parsedRepo =
+    repoSettlement?.status === "fulfilled" ? parseRepoContext(repoSettlement.value) : null;
+  const repo =
+    parsedRepo ??
+    (repoSettlement?.status === "rejected"
+      ? failedContext(repoSettlement.reason)
+      : missingFailureContext().repo);
+  const accounts =
+    authSettlement?.status === "fulfilled" ? parseAuthContext(authSettlement.value) : null;
+  return { repo, accounts };
+}
+
+async function resolveFailureContext(signal) {
+  const [repo, auth] = await Promise.allSettled([
+    runGh(repoContextArgs(), { signal }),
+    runGh(authContextArgs(), { signal }),
+  ]);
+  return buildFailureContext(repo, auth);
+}
+
+function createFailureContextCoordinator({ resolve, commit, fallback }) {
+  let epoch = 0;
+  let value = null;
+  let inFlight = null;
+
+  function ensure(signal) {
+    const captured = epoch;
+    if (value !== null) return Promise.resolve(true);
+    if (inFlight?.epoch === captured) return inFlight.promise;
+
+    const promise = Promise.resolve()
+      .then(() => resolve(signal))
+      .then(
+        (result) => {
+          if (epoch !== captured) return false;
+          commit(result);
+          value = result;
+          return true;
+        },
+        () => {
+          if (epoch !== captured) return false;
+          commit(fallback);
+          value = fallback;
+          return false;
+        },
+      )
+      .finally(() => {
+        if (inFlight?.epoch === captured) inFlight = null;
+      });
+    inFlight = { epoch: captured, promise };
+    return promise;
+  }
+
+  function invalidate() {
+    epoch += 1;
+    value = null;
+    commit(null);
+  }
+
+  return { ensure, invalidate };
+}
+
 function actionsArgs(limit) {
   return [
     "run",
@@ -714,6 +958,7 @@ function backoffActive(key, now) {
 // comes back the moment it does. "rate-limited" used to be absent for the same
 // stated reason, which had it backwards -- see RATE_LIMIT_RETRY_MS.
 const FAILURE_LADDER = {
+  "no-remote": BACKOFF_STEPS_MS,
   unavailable: BACKOFF_STEPS_MS,
   "auth-problem": AUTH_RETRY_MS,
   "rate-limited": RATE_LIMIT_RETRY_MS,
@@ -1097,6 +1342,7 @@ async function runDoctor() {
   alertBackoff.clear();
 
   const probes = [
+    ["Repository access", repoContextArgs()],
     ["Actions (run list)", actionsArgs(MIN_RUN_LIMIT)],
     ["Issues (issue list)", issuesArgs()],
     ["Pull requests (pr list)", prsArgs()],
@@ -1104,7 +1350,7 @@ async function runDoctor() {
   ];
 
   // allSettled, and every probe already resolves rather than rejects, so one
-  // slow endpoint cannot suppress the other five. runGh's own GH_TIMEOUT_MS
+  // slow endpoint cannot suppress the other six. runGh's own GH_TIMEOUT_MS
   // bounds each one.
   const [ghVersion, authStatus, remote, budget, results] = await Promise.all([
     captureGh(["--version"]),
@@ -1326,7 +1572,7 @@ const KEY_TABLE = [
   ["Tab / Shift+Tab", "Next / previous tab"],
   ["Up / Down, j / k", "Move the cursor between rows"],
   ["PgUp / PgDn", "Move a page at a time"],
-  ["Enter", "Open the selected item in your browser"],
+  ["Enter", "Open the selected item or accept a prompt"],
   ["r", "Refresh the current tab now"],
   ["?", "Show the keys (any key closes it)"],
   ["q / Esc / Ctrl+C", "Quit"],
@@ -2064,17 +2310,29 @@ const KEY_HINTS = [
   { label: "Quit", keys: "q" },
 ];
 
+const REMOTE_SETUP_HINTS = [
+  { label: "Create remote", keys: "Ent" },
+  { label: "Quit", keys: "q" },
+];
+
+const REMOTE_SETUP_LINES = [
+  "No GitHub remote found",
+  "gh-glance needs a GitHub repository to show this dashboard.",
+  "Enter  Start `gh repo create` (choose Push an existing local repository)",
+  "q/Esc  Quit, or restart with `gh-glance --repo owner/name`",
+];
+
+const REMOTE_SETUP_NONINTERACTIVE_LINES = [
+  "No GitHub remote found",
+  "Run `gh repo create` in an interactive terminal.",
+  "Choose Push an existing local repository.",
+  "Or use `gh-glance --repo owner/name`; Ctrl+C quits.",
+];
+
 // Reserved so the hints don't shift sideways every time a refresh starts and
 // finishes. Wide enough for the spinner, a space and "Fetching".
 const FETCHING_WIDTH = 12;
 
-// Width the full hint set needs: every "Label: keys" plus a " | " between each.
-// Derived from KEY_HINTS rather than written down, for the same reason
-// minimumWidthFor() derives the table breakpoint from its header descriptors --
-// a copy change must not be able to invalidate the number.
-const HINTS_FULL_WIDTH =
-  KEY_HINTS.reduce((sum, h) => sum + h.label.length + 2 + [...h.keys].length, 0) +
-  (KEY_HINTS.length - 1) * 3;
 // Compact drops the labels and keeps the keys, separated by a space:
 // "↑↓ Ent r q". No constant for its width -- nothing branches on it, and the
 // keys are short enough that it fits anywhere the frame itself does.
@@ -2087,22 +2345,24 @@ const HINTS_FULL_WIDTH =
 // bar read "Move: | Open:  | Refresh |Quit:…" -- the arrows gone, Refresh
 // missing its key, and Quit, the last entry, first to be cut. That is the one
 // hint a confused first-time user needs, in a full-screen alternate-screen app.
-const STATUS_FULL_WIDTH = FETCHING_WIDTH + HINTS_FULL_WIDTH;
-
 // Two tones rather than one flat gray: the keys you press are the part worth
 // finding at a glance, so they get the accent colour and the words describing
 // them stay dim. The accent is the panel-title cyan rather than the amber used
 // for in-progress status, so amber means exactly one thing across the product.
-function StatusBar({ fetching, spin, stale, interactive, cols }) {
+function StatusBar({ fetching, spin, stale, interactive, cols, remoteSetup = false }) {
   // Without raw mode none of the key handlers run, so advertising them would be
   // telling the user something untrue about what the app can do. Ctrl+C still
   // works there, because the tty delivers a real SIGINT.
   const hints = interactive
-    ? KEY_HINTS
+    ? remoteSetup
+      ? REMOTE_SETUP_HINTS
+      : KEY_HINTS
     : [{ label: "Quit", keys: "^C" }];
-  // Measured against the *full* set even when a compact one is rendered, so the
-  // breakpoint does not move as the bar's own contents change.
-  const compact = interactive && cols < STATUS_FULL_WIDTH;
+  const hintsFullWidth =
+    hints.reduce((sum, hint) => sum + hint.label.length + 2 + [...hint.keys].length, 0) +
+    (hints.length - 1) * 3;
+  // Measured against the active full set even when a compact one is rendered.
+  const compact = interactive && cols < FETCHING_WIDTH + hintsFullWidth;
   return e(
     Box,
     { flexDirection: "row" },
@@ -2116,7 +2376,7 @@ function StatusBar({ fetching, spin, stale, interactive, cols }) {
       e(
         Text,
         { color: fetching ? TITLE_COLOR : undefined, dimColor: !fetching },
-        `${fetching && spin ? spin : SPINNER[0]} Fetching`,
+        remoteSetup ? `${SPINNER[0]} Setup` : `${fetching && spin ? spin : SPINNER[0]} Fetching`,
       ),
     ),
     // No reserved width here, unlike the fetching slot above: this only
@@ -2186,7 +2446,7 @@ function useTerminalSize(stdout) {
 
 // ---------- App ----------
 
-function App() {
+function App({ onCreateRemote = () => {} } = {}) {
   const { stdout } = useStdout();
   const { isRawModeSupported } = useStdin();
   const { exit } = useApp();
@@ -2207,7 +2467,12 @@ function App() {
   // The `?` overlay. Renders only on a keypress, so consecutive idle frames are
   // still byte-identical and the redraw suppression is untouched.
   const [showHelp, setShowHelp] = useState(false);
+  // Set once, ICON_HINT_AFTER_MS into a first load that is still running. Never
+  // reset: it only gates a line that a resolved tab stops rendering anyway, and
+  // clearing it would cost a second state write for no visible difference.
+  const [iconHintDue, setIconHintDue] = useState(false);
   const [errors, setErrors] = useState({ actions: null, issues: null, prs: null, security: null });
+  const [failureContext, setFailureContext] = useState(null);
   const [loading, setLoading] = useState({ actions: true, issues: true, prs: true, security: true });
   const [now, setNow] = useState(new Date());
   const { rows, cols, useShortLabels } = useTerminalSize(stdout);
@@ -2219,6 +2484,14 @@ function App() {
   const [offset, setOffset] = useState({});
 
   const tab = TABS[activeIndex];
+  const tabError = errors[tab.key];
+  // Once any endpoint proves the folder has no remote, the whole dashboard is
+  // in setup mode. Keeping this tab-local made a quick tab switch replace the
+  // onboarding prompt with a second raw fetch failure while another command
+  // was still settling.
+  const remoteSetup = Object.values(errors).some(
+    (error) => error?.kind === "fetch" && error.verdict === "no-remote",
+  );
   // The not-enabled notes are collapsed into a single line. Each unavailable
   // alert source used to contribute a full-width row above the column header,
   // and on any repo without Advanced Security that is two permanent lines --
@@ -2241,7 +2514,8 @@ function App() {
   // Counts the lines actually rendered, not the notes collected -- getting this
   // wrong by one row is what makes ink repaint the whole frame.
   const extraLines =
-    (errors[tab.key] ? 1 : 0) + (tab.key === "security" ? securityLines.length : 0);
+    (tabError && !remoteSetup ? 1 : 0) +
+    (tab.key === "security" && !remoteSetup ? securityLines.length : 0);
   // Reserve lines for: the tab bar and the divider under it (2), the panel's
   // top and bottom edges (2), the column header and its separator (2), and
   // the status line (1), plus a 1-line safety margin. Slack is absorbed by
@@ -2279,6 +2553,7 @@ function App() {
   // persistently failing tab would report itself fresh forever.
   const lastOkRef = useRef({});
   const fetchTabRef = useRef(null);
+  const contextCoordinatorRef = useRef(null);
 
   const interactive = Boolean(isRawModeSupported);
 
@@ -2300,6 +2575,8 @@ function App() {
   // closure must see the current value without being rebuilt on every toggle.
   const showHelpRef = useRef(false);
   showHelpRef.current = showHelp;
+  const remoteSetupRef = useRef(false);
+  remoteSetupRef.current = remoteSetup;
 
   function moveSelection(delta) {
     const { items, key: currentKey, bodyRows: rows_, tabKey, offset: offsetRaw } = navRef.current;
@@ -2366,7 +2643,7 @@ function App() {
     // unhandled rejection.
     openInBrowser(tabKey, item)
       .catch((err) => {
-        setErrors((x) => ({ ...x, [tabKey]: shortErr(err) }));
+        setErrors((x) => ({ ...x, [tabKey]: textTabError(err) }));
       })
       .finally(() => {
         delete openingRef.current[guard];
@@ -2394,13 +2671,15 @@ function App() {
       } else if (key.pageUp) {
         moveSelection(-pageStep);
       } else if (key.return) {
-        openSelected();
+        if (remoteSetupRef.current) onCreateRemote();
+        else openSelected();
       } else if (input === "r") {
         // Goes through the same per-tab in-flight guard as the poll loop, so
         // holding the key down cannot stack concurrent subprocesses. `force`
         // bypasses (and clears) any failure backoff: this key is the user saying
         // "try again now", and a refresh that silently declined to refresh would
         // be worse than no key at all.
+        contextCoordinatorRef.current?.invalidate();
         fetchTabRef.current?.(TABS[activeIndexRef.current].key, { force: true });
       } else if (input >= "1" && input <= String(TABS.length)) {
         setActiveIndex(Number(input) - 1);
@@ -2436,6 +2715,23 @@ function App() {
     let ticks = 0;
     const controller = new AbortController();
     registerLiveAbort(controller);
+    const withTargetHost = (context) => ({
+      ...context,
+      targetHost: failureTargetHost({
+        runtimeHost: runtime.host,
+        ghHost: process.env.GH_HOST,
+        ghRepo: process.env.GH_REPO,
+        accounts: context.accounts,
+      }),
+    });
+    const coordinator = createFailureContextCoordinator({
+      resolve: async (signal) => withTargetHost(await resolveFailureContext(signal)),
+      commit: (context) => {
+        if (!cancelled) setFailureContext(context);
+      },
+      fallback: withTargetHost(missingFailureContext()),
+    });
+    contextCoordinatorRef.current = coordinator;
 
     // Each tab commits its own result the moment it lands instead of waiting on
     // a Promise.allSettled barrier. Actions is by far the slowest fetch, so
@@ -2501,13 +2797,14 @@ function App() {
         .catch((err) => {
           if (cancelled || err?.name === "AbortError") return;
           cleanRef.current[key] = false;
-          // Classified, not dumped. The three list tabs used to put raw `gh`
-          // stderr on screen while the alert path one tab over translated the
-          // same verdicts into something actionable. VERDICT_REMEDY replaces the
-          // message rather than prefixing it, because the error slot is exactly
-          // one line and a prefix would truncate away the diagnostic half.
-          const verdict = classify(err);
-          setErrors((x) => ({ ...x, [key]: pick(VERDICT_REMEDY, verdict, null) ?? shortErr(err) }));
+          // Preserve both the verdict and the bounded raw error in state. The
+          // renderer translates recognized verdicts at draw time, which lets a
+          // later repository/account context refine the one-line remedy without
+          // throwing away the original evidence.
+          const failure = toTabError(err);
+          const verdict = failure.verdict;
+          setErrors((x) => ({ ...x, [key]: failure }));
+          if (verdict === "unavailable") coordinator.ensure(controller.signal);
           // ...and back off, which the list tabs never did at all. A tab wedged
           // on an expired token used to re-spawn `gh` every tick forever -- 720
           // subprocesses an hour, indefinitely, against a token that is already
@@ -2539,6 +2836,11 @@ function App() {
     fetchTabRef.current = fetchTab;
 
     async function tick() {
+      // Setup mode owns the whole screen and can only finish by handing off to
+      // gh or exiting. Hidden tab retries cannot make that state more useful,
+      // so stop spawning subprocesses once any endpoint proves there is no
+      // remote. The interval may still wake, but this branch is otherwise idle.
+      if (remoteSetupRef.current) return;
       // Only the tab you're looking at needs to keep up with REFRESH_MS. The
       // other three exist to keep the tab-bar counts honest, which tolerates
       // being a minute behind -- so they refresh every BACKGROUND_EVERY ticks
@@ -2564,9 +2866,10 @@ function App() {
     return () => {
       cancelled = true;
       clearInterval(id);
+      if (contextCoordinatorRef.current === coordinator) contextCoordinatorRef.current = null;
       // `cancelled` stops state updates from a promise that already resolved;
       // the signal stops the subprocess itself, so quitting doesn't orphan up to
-      // six `gh` children mid-request. They cover different windows and both are
+      // eight `gh` children mid-request. They cover different windows and both are
       // needed.
       controller.abort();
     };
@@ -2600,7 +2903,7 @@ function App() {
     TABS.map((t) => [t.key, data[t.key] == null && !errors[t.key]]),
   );
   const anyFirstLoad = Object.values(firstLoad).some(Boolean);
-  const showSpinner = ANIMATE && (anyFirstLoad || hasRunningVisible);
+  const showSpinner = !remoteSetup && ANIMATE && (anyFirstLoad || hasRunningVisible);
   useEffect(() => {
     if (!showSpinner) {
       // Park on a fixed frame rather than freezing wherever the animation
@@ -2613,8 +2916,20 @@ function App() {
     return () => clearInterval(id);
   }, [showSpinner]);
 
+  // Armed on the same condition the loading line renders on, so a start that
+  // resolves inside ICON_HINT_AFTER_MS clears the timer on the way past and
+  // never writes state at all -- the fast path stays exactly as many renders as
+  // it was. `anyFirstLoad` excludes tabs that failed (see firstLoad above), so a
+  // wedged tab cannot hold this armed: an error line already says what happened,
+  // and a font hint underneath it would be answering a question nobody asked.
+  useEffect(() => {
+    if (!anyFirstLoad || iconHintDue) return;
+    const timer = setTimeout(() => setIconHintDue(true), ICON_HINT_AFTER_MS);
+    return () => clearTimeout(timer);
+  }, [anyFirstLoad, iconHintDue]);
+
   const items = data[tab.key];
-  const error = errors[tab.key];
+  const displayError = formatTabError(tabError, failureContext);
   const spin = SPINNER[frame % SPINNER.length];
 
   const counts = Object.fromEntries(
@@ -2652,7 +2967,9 @@ function App() {
       ];
     }),
   );
-  const failed = Object.fromEntries(TABS.map((t) => [t.key, Boolean(errors[t.key])]));
+  const failed = Object.fromEntries(
+    TABS.map((t) => [t.key, Boolean(errors[t.key]) && errors[t.key]?.verdict !== "no-remote"]),
+  );
 
   // Data can be arbitrarily old without anything on screen saying so: a failing
   // poll only surfaces on the tab you have selected, and after a laptop sleep
@@ -2789,15 +3106,37 @@ function App() {
       !showHelp &&
         tooNarrow &&
         e(Text, { dimColor: true, wrap: "truncate-end" }, "too narrow"),
-      !showHelp && !tooNarrow && error && e(Text, { color: ERROR_TEXT, wrap: "truncate-end" }, error),
       !showHelp &&
         !tooNarrow &&
+        !remoteSetup &&
+        displayError &&
+        e(Text, { color: ERROR_TEXT, wrap: "truncate-end" }, displayError),
+      !showHelp &&
+        !tooNarrow &&
+        !remoteSetup &&
         tab.key === "security" &&
         securityLines.map((note, i) =>
           e(Text, { key: i, dimColor: true, wrap: "truncate-end" }, note),
         ),
-      !showHelp && !tooNarrow && e(HeaderCells, { cells: header }),
-      ...(tooNarrow || showHelp ? [] : visibleItems).map((item) => {
+      !showHelp &&
+        !tooNarrow &&
+        remoteSetup &&
+        (interactive ? REMOTE_SETUP_LINES : REMOTE_SETUP_NONINTERACTIVE_LINES).map(
+          (line, index) =>
+            e(
+              Text,
+              {
+                key: `remote-setup-${index}`,
+                color: index === 0 ? TITLE_COLOR : undefined,
+                bold: index === 0,
+                dimColor: index === 1,
+                wrap: "truncate-end",
+              },
+              line,
+            ),
+        ),
+      !showHelp && !tooNarrow && !remoteSetup && e(HeaderCells, { cells: header }),
+      ...(tooNarrow || showHelp || remoteSetup ? [] : visibleItems).map((item) => {
         const key = itemKey(item);
         return e(
           RowBoundary,
@@ -2827,19 +3166,21 @@ function App() {
       // repository rather than the absence of an answer.
       !showHelp &&
         !tooNarrow &&
+        !remoteSetup &&
         visibleItems.length === 0 &&
-        !(error && items == null) &&
+        !(tabError && items == null) &&
         e(
           Text,
           { dimColor: true },
           firstLoad[tab.key]
             ? `${showSpinner ? spin : SPINNER[0]} loading ${tab.label.toLowerCase()}…` +
-              // Shown only while the first fetch is in flight, so it costs a
-              // second of one line at startup and nothing after -- and it lands
-              // exactly when someone is staring at a fresh pane deciding whether
-              // the thing works. Suppressed once icons are already ASCII, since
-              // then there is nothing to fix.
-              (USING_NERD_ICONS ? "   (icons blank? GH_GLANCE_ICONS=unicode)" : "")
+              // Appended only once a first fetch has been running for
+              // ICON_HINT_AFTER_MS, so an ordinary start never shows it: the
+              // remedy is for someone looking at a pane of blank boxes, and by
+              // then they have been looking long enough to want an explanation.
+              // Suppressed once icons are already ASCII, since then there is
+              // nothing to fix.
+              (USING_NERD_ICONS && iconHintDue ? "   (icons blank? GH_GLANCE_ICONS=unicode)" : "")
             : tab.key === "security" && securityNotes.length === ALERT_SOURCES.length
               ? "no alert sources available"
               : `no ${tab.countLabel}`,
@@ -2856,6 +3197,7 @@ function App() {
       stale: staleLabel,
       interactive,
       cols: frameCols,
+      remoteSetup,
     }),
   );
 }
@@ -2929,7 +3271,42 @@ if (IS_MAIN) {
   // root box is the terminal height. Windows is already documented as untested
   // (README Limitations), and the pty harness covers the two platforms that are
   // supported, so the flag is verified where it is claimed to work.
-  const app = render(e(App), { incrementalRendering: true });
+  let app;
+  let remoteSetupStarted = false;
+  const createRemote = () => {
+    if (remoteSetupStarted) return;
+    remoteSetupStarted = true;
+    try {
+      app?.unmount();
+    } catch {
+      // The interactive gh flow matters more than a best-effort final repaint.
+    }
+    restoreScreen();
+    abortLiveRequests();
+
+    // Plain `gh repo create` is the interactive form. Supplying --source here
+    // would switch gh to non-interactive mode and require gh-glance to choose a
+    // visibility on the user's behalf, which this consent boundary must never
+    // do. The prompt tells the user which interactive path matches this folder.
+    const child = spawn("gh", ["repo", "create"], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    setupChild = child;
+    child.once("error", (err) => {
+      if (setupChild === child) setupChild = null;
+      console.error(`gh-glance: could not start repository setup: ${redact(shortErr(err))}`);
+      process.exitCode = 1;
+    });
+    child.once("exit", (code, signal) => {
+      if (setupChild === child) setupChild = null;
+      process.exitCode = signal ? 1 : (code ?? 1);
+      if (code === 0) {
+        console.log("gh repo create finished. Run gh-glance again when this folder has a remote.");
+      }
+    });
+  };
+  app = render(e(App, { onCreateRemote: createRemote }), { incrementalRendering: true });
 
   // 128 + signal number, so a supervisor or `timeout` can tell an interrupted
   // run from a clean one. These fire on external `kill` and when raw mode is
@@ -2952,19 +3329,38 @@ if (IS_MAIN) {
   // exiting immediately afterwards keeps the prompt-exit guarantee: waiting for
   // the event loop to drain would let a hung `gh` turn Ctrl+C into an apparent
   // hang.
-  const bySignal = (code) => () => {
-    try {
-      app.unmount();
-    } catch {
-      // Teardown is best effort. restoreScreen below, and the `exit` listener
-      // above, both still run, so the terminal is handed back either way.
+  let signalExitStarted = false;
+  const bySignal = (code, signal) => () => {
+    if (signalExitStarted) return;
+    signalExitStarted = true;
+    const finish = () => {
+      try {
+        app.unmount();
+      } catch {
+        // Teardown is best effort. restoreScreen below, and the `exit` listener
+        // above, both still run, so the terminal is handed back either way.
+      }
+      restoreScreen();
+      process.exit(code);
+    };
+
+    const child = setupChild;
+    if (forwardSignalToChild(child, signal)) {
+      const force = setTimeout(() => {
+        forwardSignalToChild(child, "SIGKILL");
+        finish();
+      }, 1000);
+      child.once("exit", () => {
+        clearTimeout(force);
+        finish();
+      });
+      return;
     }
-    restoreScreen();
-    process.exit(code);
+    finish();
   };
-  process.on("SIGINT", bySignal(130));
-  process.on("SIGTERM", bySignal(143));
-  process.on("SIGHUP", bySignal(129));
+  process.on("SIGINT", bySignal(130, "SIGINT"));
+  process.on("SIGTERM", bySignal(143, "SIGTERM"));
+  process.on("SIGHUP", bySignal(129, "SIGHUP"));
 }
 
 // Exported for unit tests. The dashboard itself is still one file; these are
@@ -2983,6 +3379,16 @@ export {
   isUnavailable,
   isRateLimited,
   isAuthProblem,
+  isMissingRemote,
+  forwardSignalToChild,
+  toTabError,
+  formatTabError,
+  parseRepoContext,
+  parseAuthContext,
+  buildFailureContext,
+  failureTargetHost,
+  unavailableRemedy,
+  createFailureContextCoordinator,
   AUTH_RETRY_MS,
   BACKOFF_STEPS_MS,
   redact,
@@ -3003,6 +3409,9 @@ export {
   OCT_UNICODE,
   KEY_TABLE,
   KEY_HINTS,
+  REMOTE_SETUP_HINTS,
+  REMOTE_SETUP_LINES,
+  REMOTE_SETUP_NONINTERACTIVE_LINES,
   VERDICT_REMEDY,
   RATE_LIMIT_RETRY_MS,
   FAILURE_LADDER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-glance",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A live-refreshing GitHub dashboard for your terminal: Actions, Issues, Pull Requests, and Security alerts in one narrow pane",
   "type": "module",
   "bin": {