dsh-git-badge 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -10,12 +10,68 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-12
+
+### Added
+
+- **A hover card on the input chip.** Resting a pointer on the chip now shows what
+  the chip has no room for: the file breakdown (`✎3` split into staged / unstaged
+  / unmerged / untracked, so *ready to commit* is distinguishable from *not staged
+  yet*), the last three commits with their ages, and the stash count. When the
+  untracked walk fell back to git's collapsed count the card says `(collapsed)`
+  rather than presenting an under-count as exact.
+  The card consumes the `detail=1` payload the node half has carried unused since
+  0.6.0, and it is **lazy**: the extra fields cost a `log -3` plus a stash list, so
+  they are fetched only once a pointer rests on the chip and then kept fresh over
+  the same SSE path. A badge refresh fires on every file edit, and the everyday
+  chip still pays for none of it. It uses the shell's own seeded `Tooltip`
+  primitive — no new dependency, no seam patch — and if that primitive is ever
+  absent the chip renders uncarded rather than not at all. The boot log reports
+  which path was taken (`[dsh-git-badge] hover card = on (shell Tooltip
+  primitive).`), because the guard that keeps the badge working would otherwise
+  make a missing seed look like a missing feature.
+- **A PR / CI token on the input chip.** When the branch has a GitHub pull
+  request the chip carries `PR#142` with the rollup state (`✓` passing, `…`
+  running, `✗` failing) and a `draft` marker. It reads the PR through the user's
+  own `gh` CLI, so the plugin never handles a credential. The rollup is reduced to
+  one worst-case state (a single failure outweighs any number of successes), the
+  token carries an accessible name naming the state, and the hover card spells out
+  the check state, draft and review decision.
+- **The PR token links to the pull request.** When `gh` reports an http(s) URL the
+  token is an anchor that opens the PR in a new tab, so this browser tab keeps the
+  conversation. It underlines on hover or focus only — the at-rest signal is the
+  pointer cursor — and keeps the chip's own colour instead of the browser's link
+  blue, so it still reads as one row. Being an anchor, it is also keyboard-reachable
+  now, which the text token was not. The protocol is checked on both halves: only
+  `http:`/`https:` is carried or rendered, so a payload value can never become a
+  `javascript:` href.
+- `?pr=1` on the status route. PR/CI is asked for by the **chip only**, so a
+  sidebar that surveys twenty workspaces never spawns twenty `gh` processes. The
+  read is TTL-bounded (~90s per repository), refreshed out of band exactly like
+  the existing fetch, and notifies subscribers only when the state actually
+  changes.
+- **PR/CI degrades to an absent field, never an error.** No `gh`, a logged-out
+  `gh`, a non-GitHub remote, an offline network, a rate limit, unparseable output
+  and a timed-out call all render the unchanged chip: a caller cannot tell "no PR"
+  from "no `gh`", because neither changes what should be displayed.
+- A `runCli` helper the git and `gh` invocations now share, so `gh` inherits the
+  same timeout / missing-binary / exit-code semantics (and `GIT_TERMINAL_PROMPT`'s
+  analogue, `GH_PROMPT_DISABLED`, keeps an auth prompt from hanging a refresh).
+
+### Changed
+
+- The `detail=1` payload has a consumer at last. Its annotation said "no surface
+  consumes this yet"; the input chip's hover card is that surface, so the
+  branch/last-commits/stash fields are no longer speculative.
+- `config` gains `prStatus` (`"auto"` / `"off"`), `prTtlMs`, `prTimeoutMs` and a
+  `prRunner` test seam mirroring `gitRunner`.
+
 ## [0.7.0] - 2026-09-12
 
 ### Changed
 
 - **Both surfaces draw the same status mark.** The input chip no longer leads with
-  a 🔴/🟡/🟢 emoji dot: it renders the SAME 12px SVG mark as the sidebar row — a
+  a 🔴/🟡/🟢 emoji dot: it renders the SAME SVG mark as the sidebar row — a
   filled **circle**, or a **tree** for a linked `git worktree` — so the shape says
   *worktree or not* and the fill says *status*, identically wherever the badge
   appears. The `⑂` worktree glyph is gone with the emoji: the tree shape already
@@ -136,6 +192,7 @@ npm. 0.6.0 is the first release recorded here.
 - `detail=1` is annotated as having no consumer yet (the hover card remains
   pending). Its comment previously claimed `log -1` while the code ran `log -3`.
 
-[Unreleased]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/releases/tag/v0.8.0
 [0.7.0]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/releases/tag/v0.7.0
 [0.6.0]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/releases/tag/v0.6.0

package/README.md

@@ -3,11 +3,13 @@
 Git status badges for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
 
 - **Input-row chip** — `● main ↑0 ↓2 ✎3` next to the access picker, showing the git state of the workspace the current conversation is attached to. Works on every install.
-- **Sidebar row badges** — the same status mark floated to the right of each workspace row (`Project 1   ●`), with a linked worktree's name beside it (`Project 2   hotfix-tree 🌳`). Requires the `sidebar.workspaces.row` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
+- **Hover card** — rest a pointer on the chip for what won't fit: the file breakdown (`✎3` split into staged / unstaged / untracked), the last three commits, and the stash. Fetched only on hover, so the everyday badge pays nothing for it. Works on every install.
+- **PR / CI token** — `● main ↑0 ↓2 PR#142 ✗` when the branch has a GitHub pull request, read through your own `gh` CLI (the plugin never handles a credential). The token **links to the PR** — it opens in a new tab, and underlines when you hover or focus it. Invisible when `gh` cannot answer: not installed, not logged in, no GitHub remote, offline or rate-limited all render the unchanged chip, and a token with no URL to link to stays plain text.
+- **Sidebar row badges** — the same status mark floated to the right of each workspace row (`Project 1   ●`), with a linked worktree's name beside it (`Project 2   hotfix-tree 🌳`). Requires the `sidebar.workspaces.row` seam; without it the plugin degrades to chip-only and logs what's active to the browser console. The hover card and PR token are chip-only, so they never need the seam.
 
 The leading **mark** is identical on both surfaces: a circle filled with the status colour, or a **tree** when the workspace is a linked `git worktree`. (`●`/`🌳` stand in for it here — it is a drawn SVG so that it can take the theme's status colours.)
 
-Event-driven freshness: working trees are watched and updates push over SSE — badges flip within ~1s of any commit, stage, or edit. One `git status --porcelain=v2` call per sample. The status API takes **no path**: the caller passes a session id (chip) or workspace id (row) and the server resolves the directory itself.
+Event-driven freshness: working trees are watched and updates push over SSE — badges flip within ~1s of any commit, stage, or edit. One `git status --porcelain=v2` call per sample (plus optionally one `gh` call per ~90s, chip only). The status API takes **no path**: the caller passes a session id (chip) or workspace id (row) and the server resolves the directory itself.
 
 ## Install
 
@@ -15,7 +17,7 @@ Event-driven freshness: working trees are watched and updates push over SSE —
 dsh plugin --profile web add dsh-git-badge
 ```
 
-Restart the web process, refresh the browser. Requires Node ≥ 20 and `git` on PATH.
+Restart the web process, refresh the browser. Requires Node ≥ 20 and `git` on PATH. `gh`, on PATH and authenticated, is optional — it only enables the PR/CI token.
 
 Seam details: [github.com/Kevin-McIsaac/dsh-workspace-git-badge](https://github.com/Kevin-McIsaac/dsh-workspace-git-badge) (SEAM.md / PR.md).
 

package/lib/client.js

@@ -10,8 +10,15 @@
  *    floated right, and a worktree's name beside it. Deliberately shows NO
  *    branch: the chip is the surface that names it.
  *  - conversation.input.left (upstream): chip — status mark + branch + a
- *    worktree's name + in-progress operation token + sync/dirty suffix
- * The hover card is intentionally untouched.
+ *    worktree's name + in-progress operation token + sync/dirty suffix + the
+ *    PR/CI token, with a HOVER CARD carrying the breakdown the chip has no room
+ *    for (file detail, recent commits, stash, PR state).
+ *
+ * The hover card is the INPUT CHIP's, not the sidebar row's, and it needs
+ * nothing but the upstream slot: the Tooltip primitive is seeded by the shell
+ * itself, so the card works on a PRISTINE install with no seam patch. Its extra
+ * fields are fetched only once a pointer rests on the chip, so the everyday
+ * badge pays for none of them.
  */
 window.__ModuleLoader__.load({
 	id: "dsh-git-badge",
@@ -22,6 +29,24 @@ window.__ModuleLoader__.load({
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
 
+		/**
+		 * Shell-seeded UI primitives. `Tooltip` is handed to EVERY client bundle
+		 * by the web shell itself — it needs no `dsh.client.inject` entry and no
+		 * npm dependency (dsh-client-ui-open-in-app requires it the same way).
+		 *
+		 * Guarded, because the seed table belongs to the shell and not to this
+		 * plugin: on a shell that does not provide it the chip must still render,
+		 * just without the hover card. A missing card is a smaller failure than a
+		 * missing badge.
+		 */
+		let primitives = null;
+		try {
+			primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		} catch {
+			primitives = null;
+		}
+		const Tooltip = primitives === null ? void 0 : primitives.Tooltip;
+
 		/** Module-level git-status cache. Entries are invalidated by SSE events, never by age. */
 		const GIT_CACHE = new Map();
 		/** In-flight fetches per cacheKey: bursts collapse into one request. */
@@ -35,11 +60,21 @@ window.__ModuleLoader__.load({
 		 * one. The chip targets its conversation (`session`); a sidebar row
 		 * targets the workspace id the seam hands it. The query string doubles as
 		 * the cache key.
+		 *
+		 * The two optional additions are the INPUT CHIP's alone, and each is an
+		 * explicit request rather than something every badge pays for:
+		 *   - `detail=1` — recent commits and stash for the hover card;
+		 *   - `pr=1` — the branch's GitHub PR/CI state.
+		 * A sidebar row asks for neither, so surveying N workspaces never costs N
+		 * forge calls (see the node half's PR region).
 		 */
-		function targetQuery(target) {
+		function targetQuery(target, options) {
 			if (target === void 0 || target.id === void 0) return void 0;
 			const param = target.kind === "workspace" ? "workspace" : "session";
-			return param + "=" + encodeURIComponent(target.id);
+			let query = param + "=" + encodeURIComponent(target.id);
+			if (options?.pr === true) query += "&pr=1";
+			if (options?.detail === true) query += "&detail=1";
+			return query;
 		}
 
 		//#region SSE change feed (one EventSource per page, ref-counted)
@@ -90,16 +125,24 @@ window.__ModuleLoader__.load({
 		 * node half's watcher reports a change for this target (SSE), plus a slow
 		 * safety-net poll in case the stream dies silently. Returns undefined
 		 * while loading and for non-git workspaces.
+		 *
+		 * `options.detail` / `options.pr` ask the node half for the chip's extras
+		 * (see targetQuery). `options.enabled: false` holds the fetch back
+		 * entirely — that is what makes the hover card's extra fields LAZY: the
+		 * chip renders without them and only starts paying for `log -3` plus a
+		 * stash list once a pointer actually rests on it. The hook is still called
+		 * unconditionally (hooks may not be conditional); the GATE is inside.
 		 */
-		function useGitStatus(target) {
-			const cacheKey = targetQuery(target);
+		function useGitStatus(target, options) {
+			const enabled = options?.enabled !== false;
+			const cacheKey = targetQuery(target, options);
 			const hit = cacheKey === void 0 ? void 0 : GIT_CACHE.get(cacheKey);
 			// state carries the key it belongs to: switching conversations changes
 			// the key, and showing the previous session's badge until the new fetch
 			// lands would be wrong
 			const [state, setState] = react.useState({ key: cacheKey, data: hit === void 0 ? void 0 : hit.data });
 			react.useEffect(() => {
-				if (cacheKey === void 0) return;
+				if (cacheKey === void 0 || !enabled) return;
 				let alive = true;
 				// The workspace this target resolved to, taken from the response (the
 				// server echoes it). THIS is what events are matched against: an event
@@ -149,7 +192,7 @@ window.__ModuleLoader__.load({
 					unsubscribe();
 					clearInterval(fallback);
 				};
-			}, [cacheKey]);
+			}, [cacheKey, enabled]);
 			return state.key === cacheKey ? state.data : void 0;
 		}
 
@@ -222,6 +265,57 @@ window.__ModuleLoader__.load({
 			return parts.length > 0 ? " " + parts.join(" ") : "";
 		}
 
+		/**
+		 * PR / CI token — INPUT CHIP ONLY, and absent entirely when the node half
+		 * has nothing to say (no `gh`, no GitHub remote, no PR for the branch), so
+		 * a machine without `gh` sees precisely the chip it saw before.
+		 *
+		 * The state glyph is not the only channel: the token carries an accessible
+		 * name spelling the state out, the same rule the status mark follows.
+		 */
+		const PR_STATE_GLYPH = { passing: "\u2713", pending: "\u2026", failing: "\u2717", none: "" };
+		const PR_STATE_LABEL = { passing: "checks passing", pending: "checks running", failing: "checks failing", none: "no checks" };
+
+		/** ` PR#142 ✗` (plus ` draft`), or "" when there is no PR to report. */
+		function formatPrToken(info) {
+			const pr = info.pr;
+			if (pr === void 0 || pr === null || pr.number === void 0) return "";
+			const state = PR_STATE_GLYPH[pr.state] === void 0 ? "none" : pr.state;
+			const glyph = PR_STATE_GLYPH[state];
+			return " PR#" + pr.number + (glyph === "" ? "" : " " + glyph) + (pr.draft === true ? " draft" : "");
+		}
+
+		/** The token's accessible name: "pull request 142, checks failing, draft". */
+		function prTokenLabel(info) {
+			const pr = info.pr;
+			if (pr === void 0 || pr === null || pr.number === void 0) return void 0;
+			const state = PR_STATE_LABEL[pr.state] === void 0 ? PR_STATE_LABEL.none : PR_STATE_LABEL[pr.state];
+			return "pull request " + pr.number + ", " + state + (pr.draft === true ? ", draft" : "");
+		}
+
+		/**
+		 * The PR's web URL, or undefined — the token is a LINK only when the node
+		 * half vouched for a URL, and is plain text otherwise (no `gh`, no GitHub
+		 * remote, an unauthenticated `gh`: the token still appears, it just does not
+		 * pretend to be clickable, so there is no dead link to discover).
+		 *
+		 * The protocol is re-checked HERE even though the node half already dropped
+		 * a non-http(s) value: an `href` is the one place a payload string becomes
+		 * executable, so the element that creates it verifies its own input rather
+		 * than trusting an upstream guard to stay in place. The shell's own markdown
+		 * renderer guards its links the same way.
+		 */
+		function prLinkUrl(info) {
+			const pr = info.pr;
+			if (pr === void 0 || pr === null || typeof pr.url !== "string") return void 0;
+			try {
+				const { protocol } = new URL(pr.url);
+				return protocol === "http:" || protocol === "https:" ? pr.url : void 0;
+			} catch {
+				return void 0;
+			}
+		}
+
 		/**
 		 * In-progress operation token — INPUT CHIP ONLY (the row shows the status
 		 * tree alone). A paused rebase or cherry-pick whose conflicts are all
@@ -293,7 +387,7 @@ window.__ModuleLoader__.load({
 		};
 
 		/**
-		 * Status mark, SHARED BY BOTH SURFACES: the same 12px shape in the same fill
+		 * Status mark, SHARED BY BOTH SURFACES: the same shape in the same fill
 		 * wherever it appears, so the sidebar row and the input chip read
 		 * identically. The FILL is the status colour; the SHAPE carries
 		 * worktree-ness — a circle for a main checkout, a tree for a linked
@@ -390,6 +484,102 @@ window.__ModuleLoader__.load({
 			return react_jsx_runtime.jsx("span", { style: { display: "flex", alignItems: "center", minWidth: 0, width: "100%" }, children });
 		}
 
+		/**
+		 * The chip's `✎n` is one number for four different things; the card splits
+		 * it, so "ready to commit" is distinguishable from "not staged yet". The
+		 * collapsed caveat is the node half's own honesty flag: when the untracked
+		 * walk blew its budget the count is a DIRECTORY count, and saying so beats
+		 * presenting an under-count as exact.
+		 */
+		function formatFileBreakdown(info) {
+			const parts = [];
+			if ((info.stagedFiles || 0) > 0) parts.push(info.stagedFiles + " staged");
+			if ((info.unstagedFiles || 0) > 0) parts.push(info.unstagedFiles + " unstaged");
+			if ((info.unmergedFiles || 0) > 0) parts.push(info.unmergedFiles + " unmerged");
+			const untracked = info.untrackedFiles || 0;
+			if (untracked > 0) parts.push(untracked + " untracked" + (info.untrackedMode === "collapsed" ? " (collapsed)" : ""));
+			return parts.length === 0 ? "clean" : parts.join(" \u00B7 ");
+		}
+
+		/** The PR's full state as text, for the card: "#142 · checks failing · draft · review approved". */
+		function formatPrDetail(pr) {
+			if (pr === void 0 || pr === null || pr.number === void 0) return void 0;
+			const state = PR_STATE_LABEL[pr.state] === void 0 ? PR_STATE_LABEL.none : PR_STATE_LABEL[pr.state];
+			const bits = ["#" + pr.number, state];
+			if (pr.draft === true) bits.push("draft");
+			if (pr.review !== void 0) bits.push(String(pr.review).toLowerCase().replace(/_/g, " "));
+			if (pr.open === false) bits.push("not open");
+			return bits.join(" \u00B7 ");
+		}
+
+		const CARD_CONTAINER = {
+			display: "flex",
+			flexDirection: "column",
+			gap: "4px",
+			fontSize: "12px",
+			lineHeight: "18px",
+			maxWidth: "340px"
+		};
+		const CARD_ROW = { display: "flex", gap: "8px", alignItems: "baseline" };
+		const CARD_LABEL = { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", minWidth: "62px" };
+		const CARD_VALUE = { minWidth: 0, overflowWrap: "anywhere" };
+
+		/**
+		 * Hover card body for the input chip — INPUT CHIP ONLY. Pure presentation
+		 * over fields the status response already carries, plus the `detail=1`
+		 * additions (recent commits, stash) when they have arrived. Everything is
+		 * spelled out in text, so no fact here depends on a colour or a glyph.
+		 */
+		function HoverCard({ info, detail }) {
+			// the detail payload is a superset of the plain one, so it wins when it
+			// has landed; until then the card still shows the base facts
+			const data = detail === void 0 ? info : detail;
+			const rows = [];
+			const add = (label, value) => {
+				if (value === void 0 || value === null || value === "") return;
+				rows.push(
+					react_jsx_runtime.jsxs("div", {
+						style: CARD_ROW,
+						children: [
+							react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: label }),
+							react_jsx_runtime.jsx("span", { style: CARD_VALUE, children: value })
+						]
+					}, label)
+				);
+			};
+			add("branch", info.branch);
+			add("upstream", info.upstream === void 0 ? "none configured" : info.upstream);
+			if (info.ahead !== void 0 || info.behind !== void 0) {
+				add("sync", "\u2191" + (info.ahead || 0) + " \u2193" + (info.behind || 0));
+			}
+			add("files", formatFileBreakdown(info));
+			add("operation", info.operation === void 0 || info.operation === null ? void 0 : String(info.operation));
+			add("pull request", formatPrDetail(data.pr));
+			if (Array.isArray(data.lastCommits) && data.lastCommits.length > 0) {
+				rows.push(
+					react_jsx_runtime.jsxs("div", {
+						style: CARD_ROW,
+						children: [
+							react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: "commits" }),
+							react_jsx_runtime.jsx("span", {
+								style: { ...CARD_VALUE, display: "flex", flexDirection: "column", gap: "2px" },
+								children: data.lastCommits.map((commit) =>
+									react_jsx_runtime.jsxs("span", {
+										children: [
+											react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: commit.hash }),
+											" " + commit.subject + (commit.when === "" ? "" : " \u00B7 " + commit.when)
+										]
+									}, commit.hash)
+								)
+							})
+						]
+					}, "commits")
+				);
+			}
+			add("stash", data.stashCount === void 0 ? void 0 : data.stashCount + " stashed");
+			return react_jsx_runtime.jsx("div", { style: CARD_CONTAINER, children: rows });
+		}
+
 		//#region composer chip (upstream additive surface: conversation.input.left)
 		/**
 		 * Chip line in the input row: git state of the workspace the CURRENT
@@ -399,17 +589,32 @@ window.__ModuleLoader__.load({
 		 * (conversation.input.left is an upstream additive slot), and stays useful
 		 * next to the sidebar rows because it is context-anchored ("where am I")
 		 * rather than surveying.
+		 *
+		 * This is the ONLY surface that asks the node half for the extras (`pr=1`
+		 * always, `detail=1` on hover), because it is the only one that renders
+		 * them — see targetQuery.
 		 */
 		function ComposerGitChip({ sessionId }) {
-			// no detail=1: nothing renders lastCommits / stashCount yet, and asking
-			// for them would add a log -3 plus a stash list to every refresh
-			const info = useGitStatus(sessionId === void 0 ? void 0 : { kind: "session", id: sessionId });
+			const target = sessionId === void 0 ? void 0 : { kind: "session", id: sessionId };
+			// the PR/CI token is always on the chip, so its fetch is not gated
+			const info = useGitStatus(target, { pr: true });
+			// The card's extras cost a `log -3` plus a stash list, so they are
+			// fetched only once a pointer actually RESTS on the chip, then kept
+			// fresh by the same SSE path. Eagerly asking would add both invocations
+			// to every refresh — and a refresh fires on every file edit.
+			const [hovered, setHovered] = react.useState(false);
+			// the PR token's own hover/focus state: it underlines on hover (and on
+			// focus) rather than at rest, and that underline is applied inline below
+			const [linkHover, setLinkHover] = react.useState(false);
+			const detail = useGitStatus(target, { pr: true, detail: true, enabled: hovered });
 			if (info === void 0 || info.git !== true) return null;
 			// the mark is an element now rather than a leading glyph in the string, so
 			// the SAME StatusMark the sidebar row draws carries the status here too;
 			// the container's 4px gap supplies the space the emoji's own did
 			const text = info.branch + formatWorktreeToken(info) + formatOperationToken(info) + formatGitSuffix(info);
-			return react_jsx_runtime.jsx("span", {
+			const prToken = formatPrToken(info);
+			const prUrl = prLinkUrl(info);
+			const chip = react_jsx_runtime.jsxs("span", {
 				style: {
 					display: "inline-flex",
 					alignItems: "center",
@@ -421,11 +626,63 @@ window.__ModuleLoader__.load({
 					whiteSpace: "nowrap",
 					cursor: "default"
 				},
+				// the card is fetched for a pointer that RESTS here, not one that
+				// merely crosses the chip
+				onPointerEnter: () => setHovered(true),
 				children: [
 					react_jsx_runtime.jsx(StatusMark, { key: "mark", info }),
-					react_jsx_runtime.jsx("span", { key: "text", children: text })
+					react_jsx_runtime.jsx("span", { key: "text", children: text }),
+					prToken === ""
+						? null
+						: prUrl === void 0
+							? react_jsx_runtime.jsx("span", {
+									key: "pr",
+									// the glyph is not the only channel: the token says what the
+									// CI state IS, for anyone who cannot see it
+									"aria-label": prTokenLabel(info),
+									children: prToken
+								})
+							: react_jsx_runtime.jsx("a", {
+									key: "pr",
+									href: prUrl,
+									// a new tab, because navigating THIS one away from the app
+									// would lose the conversation; noopener/noreferrer keep the
+									// opened tab from getting a handle on it
+									target: "_blank",
+									rel: "noopener noreferrer",
+									"aria-label": prTokenLabel(info) + ", opens on GitHub in a new tab",
+									// the chip's own colour rather than the browser's link blue /
+									// visited purple, so the token still reads as one row. The
+									// affordance is the pointer cursor plus an underline on hover
+									// or focus, set HERE rather than left to the host stylesheet:
+									// a shell that resets anchors would otherwise drop it silently.
+									style: {
+										color: "inherit",
+										textDecoration: linkHover ? "underline" : "none",
+										cursor: "pointer"
+									},
+									// focus joins hover — the token is keyboard-reachable now, and a
+									// keyboard user needs the same "this is a link" signal
+									onPointerEnter: () => setLinkHover(true),
+									onPointerLeave: () => setLinkHover(false),
+									onFocus: () => setLinkHover(true),
+									onBlur: () => setLinkHover(false),
+									children: prToken
+								})
 				]
 			});
+			// No Tooltip primitive (a shell that does not seed it): render the chip
+			// itself rather than losing the badge. The card is an enhancement, the
+			// badge is the feature.
+			if (Tooltip === void 0) return chip;
+			return react_jsx_runtime.jsx(Tooltip, {
+				side: "top",
+				maxWidth: 360,
+				// a function label keeps the card's element tree out of every render
+				// until the tooltip actually opens
+				label: () => react_jsx_runtime.jsx(HoverCard, { info, detail }),
+				children: chip
+			});
 		}
 		//#endregion
 
@@ -474,10 +731,25 @@ window.__ModuleLoader__.load({
 			}, ComposerGitChip));
 			const seamDeclared = ctx.slots.spec("sidebar.workspaces.row") !== void 0;
 			console.info("[dsh-git-badge] surfaces: input chip = on; sidebar rows = " + (seamDeclared ? "on (seam present)." : "awaiting the sidebar.workspaces.row seam — the line above reports it if it appears."));
+			// The hover card depends on a primitive the SHELL seeds, not on anything
+			// this plugin declares. Report the outcome rather than letting a missing
+			// seed look like a missing feature: the try/catch above deliberately keeps
+			// the badge working, which would otherwise make this failure silent.
+			console.info(
+				"[dsh-git-badge] hover card = " +
+					(Tooltip === void 0
+						? "off (this shell seeds no Tooltip primitive) — the chip renders uncarded."
+						: "on (shell Tooltip primitive).")
+			);
 		}
 
 		exports.apply = apply;
 		exports.inject = inject;
+		// ---------- test-only exports ----------
+		// Additive; the host reads apply/inject and ignores the rest. The suite
+		// drives these to assert the REQUEST contract — which surface asks for the
+		// expensive extras — without a browser, a fetch or a network.
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail };
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -44,9 +44,14 @@
  *       on the first refresh after each TTL window. `GIT_TERMINAL_PROMPT=0`, the
  *       shared timeout and the TTL bound keep an offline or slow remote harmless;
  *       on failure the stale-ref answer simply stands.
- *     - `detail=1` adds one `log -3` plus a stash count. NOTE: no surface
- *       consumes this yet (see the annotation on gitStatus) — it is kept for
- *       the planned hover card, and never paid for by row refresh.
+ *     - `detail=1` adds one `log -3` plus a stash count, and `pr=1` adds the
+ *       branch's GitHub PR/CI state read through the user's own `gh` CLI. Both
+ *       serve the input chip only — the hover card and the PR token — so a
+ *       sidebar row refresh pays for neither. The PR read is TTL-bounded and
+ *       out of band, like the fetch; it degrades to an ABSENT field rather than
+ *       an error whenever `gh` cannot answer (see the PR region).
+ *     - `pr=1` requires `gh` on PATH and authenticated for a token to appear.
+ *       The plugin never handles the credential: `gh` owns it.
  *
  *   GET /api/git-badge/events   (text/event-stream)
  *     - pushes `{ path }` dirty notifications the moment a workspace's git
@@ -100,23 +105,48 @@ const config = {
 	 * collapsed-fallback branch deterministically — a real sub-millisecond budget
 	 * would just race git's own startup.
 	 */
-	gitRunner: null
+	gitRunner: null,
+	/**
+	 * PR / CI status via the `gh` CLI: "auto" reads it where `gh` can answer and
+	 * silently shows nothing where it cannot; "off" never invokes `gh` at all.
+	 * Only the input chip asks for it, so a sidebar-only view spawns no forge
+	 * process — see the PR region.
+	 */
+	prStatus: "auto",
+	/** minimum interval between forge refreshes per repository */
+	prTtlMs: 90000,
+	/**
+	 * Forge call budget. Unlike git this is a network round trip to GitHub, so
+	 * it gets a more generous budget than the status sample — but it is bounded
+	 * all the same, because nothing here may hang the route.
+	 */
+	prTimeoutMs: 6000,
+	/**
+	 * Invoker for the `gh` CLI; null means the real runCli. The suite substitutes
+	 * one so every degradation path (no gh, logged out, no PR, garbage output,
+	 * timeout) is covered with no gh, no network and no forge.
+	 */
+	prRunner: null
 };
 
 /**
- * Run git in dir. Resolves { stdout } on success; on failure { stdout: null }
- * plus exactly one of: timeout (execFile timeout kill), missing (no git
- * binary), or exitCode (git ran and rejected — e.g. "not a repository").
- * The exitCode/timeout distinction separates a definitive answer (non-repo)
- * from a transient one (degraded).
+ * Run an external command in a directory. Resolves { stdout } on success; on
+ * failure { stdout: null } plus exactly one of: timeout (execFile timeout kill),
+ * missing (no such binary), or exitCode (the command ran and rejected — e.g.
+ * "not a repository", or `gh` reporting no pull request).
+ *
+ * The exitCode/timeout/missing trichotomy is what lets a CALLER tell a
+ * definitive answer from a transient one: a missing `gh` and a `gh` that says
+ * "no PR" are different facts, and only the caller knows which of them it can
+ * act on. Shared by git and `gh` so neither grows its own timeout semantics.
  */
-function runGit(dir, args, opts) {
-	const { env, timeout = config.gitTimeoutMs } = opts ?? {};
+function runCli(cmd, args, opts) {
+	const { cwd, env, timeout = config.gitTimeoutMs } = opts ?? {};
 	// env is a full replacement for execFile; overlay onto process.env so
 	// PATH/HOME (credential helpers, global config) survive
 	const fullEnv = env === void 0 ? void 0 : { ...process.env, ...env };
 	return new Promise((resolve) => {
-		execFile("git", args, { cwd: dir, timeout, env: fullEnv }, (error, stdout) => {
+		execFile(cmd, args, { cwd, timeout, env: fullEnv }, (error, stdout) => {
 			if (error === void 0 || error === null) resolve({ stdout: String(stdout) });
 			else if (error.killed) resolve({ stdout: null, timeout: true });
 			else if (error.code === "ENOENT") resolve({ stdout: null, missing: true });
@@ -125,6 +155,15 @@ function runGit(dir, args, opts) {
 	});
 }
 
+/**
+ * Run git in dir. A thin specialization of runCli: the contract above is
+ * unchanged, and `config.gitRunner` still substitutes for the whole call so the
+ * suite can force the timeout branch.
+ */
+function runGit(dir, args, opts) {
+	return runCli("git", args, { ...opts, cwd: dir });
+}
+
 /** Marker response for a git invocation that failed or timed out (transient). */
 const GIT_DEGRADED = { git: false, error: "git unavailable (timeout or failure)" };
 
@@ -178,6 +217,167 @@ async function maybeFetch(toplevel) {
 }
 //#endregion
 
+//#region PR / CI status (gh)
+/**
+ * GitHub pull-request and check state for the current branch, read through the
+ * user's own `gh` CLI.
+ *
+ * Why the CLI and not the REST API: `gh` already owns the user's credentials in
+ * its own config, so this plugin never reads, stores, caches or forwards a
+ * token. There is no secret here to leak and no OAuth flow to maintain — and a
+ * machine that has never authenticated `gh` simply gets no PR token.
+ *
+ * Degradation is a MISSING FIELD, never an error. A machine without `gh`, a
+ * logged-out `gh`, a remote that is not GitHub, an offline network, a forge rate
+ * limit, unparseable output and a timed-out call all produce exactly the same
+ * response: no `pr` key at all. That is the honest answer, because in every one
+ * of those cases the badge has nothing to say — and a caller that could tell
+ * "no PR" from "no gh" would still not know what to draw.
+ *
+ * Like the fetch above this is TTL-bounded and NEVER awaited by the route: the
+ * cached value is served immediately and a refresh that CHANGES it notifies
+ * subscribers, so the request that lapses the window carries the previous answer
+ * and the follow-up carries the new one. A forge round trip must never become
+ * badge latency.
+ */
+/** toplevel -> { lastAttemptAt, inFlight, value }; `value` undefined = nothing to say. */
+const prState = new Map();
+
+/** Test seam: the CLI invoker `gh` calls go through, so no test needs `gh`. */
+function runPrCli(cmd, args, opts) {
+	return (config.prRunner ?? runCli)(cmd, args, opts);
+}
+
+/**
+ * Does `origin` point at github.com? A cheap LOCAL call, so a non-GitHub repo
+ * never pays for a `gh` process. Deliberately scoped to origin: that is the
+ * remote `gh` itself resolves the repository from, so agreeing with it here is
+ * what keeps the two from disagreeing later.
+ */
+async function originIsGitHub(toplevel) {
+	const out = await runGit(toplevel, ["remote", "get-url", "origin"]);
+	if (out.stdout === null) return false;
+	return /(^|[/@.])github\.com[:/]/i.test(out.stdout.trim());
+}
+
+/**
+ * Reduce a `statusCheckRollup` to ONE worst-case state, so the chip needs a
+ * single colour rather than a list.
+ *
+ * Two entry shapes share the array: a CheckRun carries `status` + `conclusion`,
+ * a StatusContext carries `state` alone. A single failure outweighs any number
+ * of successes and pending checks — "mostly passing" is not a thing a red/green
+ * token can express — so failure returns immediately and pending only wins over
+ * an otherwise all-successful set.
+ */
+function summarizeChecks(checks) {
+	let sawAny = false;
+	let sawPending = false;
+	for (const check of checks) {
+		const state = String(check?.state ?? "").toUpperCase();
+		const status = String(check?.status ?? "").toUpperCase();
+		const conclusion = String(check?.conclusion ?? "").toUpperCase();
+		sawAny = true;
+		const failed =
+			["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(state) ||
+			["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(conclusion);
+		if (failed) return "failing";
+		// unfinished: a CheckRun that has not completed, or a StatusContext PENDING
+		if (state === "PENDING" || (status !== "" && status !== "COMPLETED")) sawPending = true;
+	}
+	if (!sawAny) return "none";
+	return sawPending ? "pending" : "passing";
+}
+
+/** The compact PR shape the chip renders, or undefined when there is nothing to say. */
+function summarizePr(json) {
+	if (json === null || typeof json !== "object") return void 0;
+	const number = Number.isFinite(json?.number) ? json.number : void 0;
+	if (number === void 0) return void 0;
+	const pr = {
+		number,
+		state: summarizeChecks(Array.isArray(json.statusCheckRollup) ? json.statusCheckRollup : []),
+		// draft and review state are separate from CI: a draft with green checks
+		// is not ready, and a blocked review is not a failing build
+		draft: json.isDraft === true,
+		open: String(json.state ?? "OPEN").toUpperCase() === "OPEN"
+	};
+	// omitted, not present-and-undefined: absence is the contract for "nothing to
+	// say" throughout this half, so a consumer tests the key, never the value
+	if (typeof json.reviewDecision === "string" && json.reviewDecision !== "") pr.review = json.reviewDecision;
+	// The chip links the token to the PR, so `url` is the one field that becomes an
+	// `href`: only http(s) is emitted, and anything else is omitted like every
+	// other "nothing to say" field, so a payload value cannot reach an anchor as a
+	// `javascript:` URL. The client re-checks before it builds the href — this half
+	// is the authority on what it vouches for, not the only guard.
+	if (typeof json.url === "string" && json.url !== "") {
+		try {
+			const { protocol } = new URL(json.url);
+			if (protocol === "http:" || protocol === "https:") pr.url = json.url;
+		} catch {
+			// not a URL at all — omitted, exactly like an absent one
+		}
+	}
+	return pr;
+}
+
+/**
+ * Read PR state for `branch`, or undefined. NEVER throws and never rejects: a
+ * forge is an optional luxury, so every failure path is "nothing to say".
+ */
+async function readPrStatus(toplevel, branch) {
+	// a detached HEAD is not a branch `gh` can resolve a PR for
+	if (typeof branch !== "string" || branch === "" || branch.startsWith("HEAD")) return void 0;
+	if (!(await originIsGitHub(toplevel))) return void 0;
+	const out = await runPrCli("gh", ["pr", "view", branch, "--json", "number,state,isDraft,reviewDecision,statusCheckRollup,url"], {
+		cwd: toplevel,
+		timeout: config.prTimeoutMs,
+		// GH_PROMPT_DISABLED: an auth prompt must never hang the refresh (the gh
+		// analogue of the git fetch's GIT_TERMINAL_PROMPT=0). The pager vars keep
+		// gh from waiting on a pager that will never answer, and NO_COLOR keeps
+		// escape codes out of the JSON.
+		env: { GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1" }
+	});
+	if (out.stdout === null) return void 0;
+	let json;
+	try {
+		json = JSON.parse(out.stdout);
+	} catch {
+		return void 0;
+	}
+	return summarizePr(json);
+}
+
+/**
+ * PR state for toplevel: the value to serve NOW (possibly undefined, possibly
+ * stale), spawning an out-of-band refresh when the TTL has lapsed. `notify` is
+ * called only when the refreshed value CHANGES, so an unchanged answer costs one
+ * forge call per TTL and zero SSE traffic.
+ */
+function prStatusFor(toplevel, branch, notify) {
+	if (config.prStatus === "off") return void 0;
+	const now = Date.now();
+	const state = prState.get(toplevel);
+	if (state !== void 0) {
+		// Fresh, or a refresh is already running: serve what we have either way.
+		if (now - state.lastAttemptAt < config.prTtlMs || state.inFlight !== null) return state.value;
+	}
+	const record = { lastAttemptAt: now, inFlight: null, value: state?.value };
+	const inFlight = (async () => {
+		const value = await readPrStatus(toplevel, branch).catch(() => void 0);
+		const changed = JSON.stringify(record.value ?? null) !== JSON.stringify(value ?? null);
+		record.lastAttemptAt = Date.now();
+		record.inFlight = null;
+		record.value = value;
+		if (changed) notify(toplevel);
+		return value;
+	})();
+	record.inFlight = inFlight;
+	prState.set(toplevel, record);
+	return record.value;
+}
+//#endregion
+
 /**
  * Parse `git status --porcelain=v2 --branch` output.
  * Headers: `# branch.head <name>` (or `(detached)`), `# branch.upstream
@@ -259,11 +459,12 @@ function operationMarker(gitDir) {
  * worktree reports that worktree (the toplevel walk starts above it), which is
  * the same whole-repository rule as above.
  *
- * `wantDetail` has no consumer yet: both surfaces fetch without `detail=1`.
- * The branch is retained for the planned hover card — nothing renders
- * lastCommits / stashCount today.
+ * `wantDetail` serves the input chip's HOVER CARD (recent commits + stash) and
+ * `wantPr` its PR/CI token. They are asked for separately and by the chip only,
+ * so neither is paid for by a sidebar row refresh: a row needs status and
+ * identity, nothing more.
  */
-async function gitStatus(dir, wantDetail) {
+async function gitStatus(dir, wantDetail, wantPr) {
 	// one invocation answers both questions: the repository root (so a
 	// subdirectory workspace reports the whole repo) and the per-worktree git
 	// dir (where the operation markers above live)
@@ -360,6 +561,15 @@ async function gitStatus(dir, wantDetail) {
 			if (count > 0) info.stashCount = count;
 		}
 	}
+	// PR / CI is the INPUT CHIP's business, so it is asked for explicitly
+	// (`?pr=1`) rather than paid for by every sidebar row: a row that surveys
+	// twenty workspaces must not spawn twenty forge processes. Served from the
+	// TTL cache and refreshed out of band, exactly like the fetch above — the
+	// forge round trip is never route latency.
+	if (wantPr) {
+		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
+		if (pr !== void 0) info.pr = pr;
+	}
 	return info;
 }
 
@@ -675,7 +885,8 @@ function apply(ctx) {
 					return;
 				}
 				const detail = url.searchParams.get("detail") === "1";
-				const info = await gitStatus(target.path, detail);
+				const pr = url.searchParams.get("pr") === "1";
+				const info = await gitStatus(target.path, detail, pr);
 				// Echo the resolved workspace id. SSE events identify the workspace,
 				// not the session, so a session-targeted client has no other way to
 				// tell whether an event belongs to it — without this the input chip
@@ -757,9 +968,15 @@ export {
 	operationMarker,
 	outerGitDir,
 	parseStatusV2,
+	runCli,
 	runGit,
 	gitStatus,
 	resolveWorkspace,
+	readPrStatus,
+	summarizePr,
+	summarizeChecks,
+	prStatusFor,
+	prState,
 	watchWorkspace,
 	unwatchWorkspace,
 	syncWatchers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Git status badges for DeepSeek Harness: sidebar workspace rows (via the sidebar.workspaces.row seam) and an input-row chip showing the current conversation's workspace git state. Event-driven freshness over SSE.",
   "type": "module",
   "main": "lib/index.js",