dsh-git-badge 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -10,6 +10,113 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-16
+
+### Added
+
+- **The PR token has its own hover: the commits in that pull request.** `PR#47 ✓`
+  now shows the commits on the branch that are not on the base
+  (`git log <base>..HEAD`, capped at 10 with "… and k more"), in the same line
+  format as the branch hover's list — hash, subject, compressed age, full-width
+  with ellipsis. Nothing else rides it: the token already states the number and
+  CI state, so the one question left is what is in it. Hover-gated with the rest
+  of `detail=1`, and the total reuses the ahead count already computed.
+- **`/gh clean [<path>...]` appears in the `/gh` menu behind a risk gate.** The
+  menu is built from status, not from this skill's prose, so the verb is offered
+  there whenever untracked files exist — always last, never as the badge's
+  suggested action, and carrying the host's own `RiskConfirmation`: Confirm
+  stays disabled until "I understand untracked files cannot be recovered" is
+  ticked. That gate names the risk; the agent then names the files
+  (`git clean -n`, quoted back) and asks again before `git clean -f`.
+- **A `/gh clean [<path>...]` verb, confirm-first by construction.** Removing
+  untracked files is the one operation with no reflog and no stash entry, so the
+  verb's first step is always `git clean -n -- <paths>` with the output quoted
+  back verbatim (the user approves the list, not the idea), then an explicit yes,
+  then `git clean -f -- <paths>` on named paths only. `-x`, `-d` and bare
+  `git clean -f` are forbidden — ignored files are often credentials and `-d`
+  turns one path into a tree. It stays out of the badge's ranked suggestions: a
+  destructive action the agent cannot infer intent for is never suggested, only
+  available on request.
+
+### Changed
+
+- **The session row's action token only appears when the session is idle.** A turn
+  in flight is exactly when a git suggestion is noise: the checkout is still
+  moving and the agent has not finished. The row reads its run state from the
+  shell's standard kit — `useSessions`, the same selector hook the workspace UI
+  itself uses — and renders nothing while that session is `running`. The filter is
+  on render, not on the fetch, so the row's hover line is unaffected. On a shell
+  that seeds no such hook the row behaves as before, and the console says which of
+  the two it got.
+- **The PR/CI token stops lagging behind the forge.** The forge read is
+  TTL-bounded and its refresh is request-driven, while an idle chip only asks
+  every 60s — so the old 90s `prTtlMs` silently suppressed every other poll, and
+  a pull request that appeared on GitHub with no local git event to announce it
+  could take ~2.5 minutes to show up. At 20s the TTL no longer outlives the
+  client's poll, so the first refresh after the forge changes picks it up and the
+  worst case falls to roughly the poll interval. Cost: up to one `gh pr view` per
+  open chip per minute, where it was one per ~2 minutes.
+- **The branch hover shows only the merge axis.** `upstream` and `sync` are gone
+  — they stated the same divergence against the branch's own remote, in arrows,
+  when `merge` already states it against the base branch in words. The `merge`
+  row now ALWAYS renders: `ready to merge`, `blocked: draft | review required |
+  checks failing`, `no pull request`, each joined with `N ahead, M behind main`
+  when those counts are known. A row that can be absent is a row the reader has
+  to reconstruct.
+- The commit cells lost their trailing colon (a later change had reintroduced it
+  after the earlier removal), so both hovers read `abc1234  subject · 2h ago`.
+- **One action list, built by the server.** Both halves used to derive the
+  pull/push/commit/pr conditions, and the copies drifted: the card once promoted
+  a client-only extra into its action row, and `/gh pr` was offered on the
+  default branch. The node half now publishes `actions` — the ranked rules in the
+  configured order with the top entry flagged `primary` (also served as `next`,
+  on every response), then the standing options (`pr view <n>`, `pr`, and the
+  flagged `clean`). `merge <n>` becomes a standing entry whenever the PR is
+  mergeable, so it now appears alongside a primary `push`/`pull` instead of only
+  when it wins the ranking. The client renders the list verbatim and keeps only
+  presentation — labels and the clean risk gate; `actions` rides the `pr=1`
+  payload only, so sidebar rows stay lean. Net: ~65 lines of duplicated client
+  rules deleted, and the conditions are unit-tested where the data lives.
+- **The upstream sync numbers ride the branch's hover and link.** `↑a ↓b` were
+  rendered inside the file count's names tooltip and outside the branch's compare
+  link, though they are the branch's standing against its upstream — so they now
+  sit with the branch name: same lineage hover, same compare-view link, and the
+  link's accessible name says "N ahead and M behind upstream". `✎n` keeps its own
+  names tooltip. Visible side effect: the arrows render before a paused-operation
+  token rather than after it.
+
+### Fixed
+
+- **The PR token's hover lines its commits up like the branch hover.** Both lists
+  now come from one renderer: a fixed-width monospace hash cell, so every
+  description starts on the same column and the list reads as a table. The PR
+  list had reused the card's label style, whose `minWidth` and `flex` only apply
+  inside a flex row — on a plain inline span they did nothing, so the hash sat
+  flush against its description with the columns ragged.
+- **The PR token's hover is reachable by hovering the token itself.** The commits
+  it lists are detail-only, and only the status mark and the branch name enabled
+  the `detail=1` fetch — so a pointer that went straight to `PR#47 ✓` had rested
+  on nothing that fetches, and its hover could not open until the mark had been
+  hovered first. The token is now its own detail gate, in both its linked and
+  plain forms.
+- **No more "open a pull request" on `main`, and the hover card shows only the
+  server's verdict.** Two layers disagreed: the node half correctly returned
+  nothing to do for a clean, synced default branch, while the client's extras
+  still offered `/gh pr` — and the card promoted that extra into its `action:`
+  row, so a checkout with nothing to do displayed a suggestion. The node half now
+  resolves the repository's default branch (`refs/remotes/origin/HEAD`,
+  TTL-cached and refreshed out of band like the fetch, so the hot path pays
+  nothing) and flags it on the response; the `pr` extra is suppressed when the
+  branch IS that default; and the card's action row reads the server's `next`
+  directly, leaving the extras to the `/gh` picker where they belong.
+- **The seam suite no longer writes into your real `~/.dsh/git-badge-seam`.**
+  One block spawned the postinstall hook without `SEAM_DATA_DIR`, so the hook
+  resolved its store to the machine's actual data directory: a test run
+  overwrote the real `backup-client.js`/`backup-index.js` and left a
+  `restart-pending.json` behind. It passed on CI only because the runner's
+  `$HOME` is writable — under a read-only `$HOME` it failed with EROFS. The
+  block now takes a throwaway data dir like the rest of the file.
+
 ## [0.16.1] - 2026-09-16
 
 ### Fixed

package/README.md

@@ -6,12 +6,12 @@ Git status badges for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek
 - **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.
 - **Worktree-aware** — a conversation's directory is fixed when it is created, so a conversation that does its work in a linked `git worktree` would otherwise keep reporting the main checkout. The session registers its checkout (`npx dsh-git-badge-checkout <path>`, run by the git-worktree and `/gh checkout` paths), and the badge describes **that worktree** instead — its branch, counts, tree mark and PR/CI token (`🌳 chore/global-skills-tiering ↑0 ↓2 PR#391 ✓` rather than `● main`). The hover card names the tree in a `worktree` row and adds a `checkout` row with the conversation's own directory, so the main checkout's branch and dirty state stay one hover away. Registrations are advisory: git's own worktree list validates the path, entries expire after 24h, and a workspace-targeted row always reports the checkout the registry owns.
-- **Sidebar session-row action token** — each session row shows the ONE thing that conversation needs from you, or nothing at all: `merge`, `fix CI`, `review`, `resolve`, `pull`, `push`. It is triage rather than status: `merge` appears only when GitHub itself reports `mergeStateStatus: CLEAN`, and every waiting state (draft, blocked, behind, checks still running) stays silent. Hovering the row adds a line naming the checkout and the pull request the action refers to. The token floats to the right of the row, is set heavier than the timestamp beside it, and is coloured by how much it needs you — red for a conflict or a failing build, amber for a requested review, green for `merge`, quiet grey for routine sync. Requires the `sidebar.workspaces.sessionRow` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
+- **Sidebar session-row action token** — each session row shows the ONE thing that conversation needs from you, or nothing at all: `merge`, `fix CI`, `review`, `resolve`, `pull`, `push`. It is triage rather than status: `merge` appears only when GitHub itself reports `mergeStateStatus: CLEAN`, and every waiting state (draft, blocked, behind, checks still running) stays silent. Hovering the row adds a line naming the checkout and the pull request the action refers to. The token floats to the right of the row, is set heavier than the timestamp beside it, and is coloured by how much it needs you — red for a conflict or a failing build, amber for a requested review, green for `merge`, quiet grey for routine sync. It appears only when the session is **idle** — while a turn is running the row stays quiet, because the checkout is still moving and a suggestion would describe a state that is about to change. Requires the `sidebar.workspaces.sessionRow` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
 - **Nothing on workspace rows.** A workspace cannot know which worktree its conversations are using, so a per-workspace badge could only guess or report the main checkout. The seam is on the session row for that reason.
 
 The leading **mark** belongs to the input chip: a circle filled with the status colour, or a **tree** when the checkout is a linked `git worktree`. The sidebar row deliberately carries no mark — see the row bullet above, where one word does the job a colour cannot. (`●`/`🌳` 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, including inside a linked worktree the session registered. One `git status --porcelain=v2` per sample, shared by every surface pointing at the same checkout, plus at most one `gh` read per repository-and-branch per ~90s. The status API takes **no path**: the caller passes a session id (chip and sidebar rows) or a workspace id, 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, including inside a linked worktree the session registered. One `git status --porcelain=v2` per sample, shared by every surface pointing at the same checkout, plus at most one `gh` read per repository-and-branch per ~20s. The status API takes **no path**: the caller passes a session id (chip and sidebar rows) or a workspace id, and the server resolves the directory itself.
 
 Diagrams, the hover card's full field list and a walkthrough for git newcomers live
 in the [repo README](https://github.com/Kevin-McIsaac/dsh-workspace-git-badge) —

package/lib/client.js

@@ -232,45 +232,40 @@ window.__ModuleLoader__.load({
 
 
 		/**
-		 * The /gh picker's sub-actions — the skill invocations the checkout
-		 * justifies, most urgent first. The server's `next` (the ranked top rule,
-		 * already carrying args/why/what) always leads; the client adds the other
-		 * justified actions as secondary entries, mirroring the server's category
-		 * rules but never re-deciding the winner.
+		 * The actions BOTH surfaces render — the server's list, verbatim.
+		 *
+		 * This half used to re-derive pull/push/commit/pr from the raw counts,
+		 * which meant two implementations of the same conditions drifting apart:
+		 * the card once promoted a client-only extra into its action row, and
+		 * `/gh pr` was offered on the default branch. The node half owns the
+		 * rules and the ranking now; the client adds presentation only — the risk
+		 * gate for `clean`, and the labels.
+		 *
+		 * Falls back to the single `next` for a payload from an older node half.
 		 */
 		function ghSkillActions(info) {
 			if (info === void 0 || info === null || info.git !== true) return [];
-			const subs = [];
-			const seen = new Set();
-			const add = (args, why, what) => {
-				if (args === void 0 || args === null || args === "" || seen.has(args)) return;
-				seen.add(args);
-				subs.push({ args, why, what });
+			if (Array.isArray(info.actions)) return info.actions;
+			return info.next === void 0 || info.next === null ? [] : [info.next];
+		}
+
+		/**
+		 * The risk gate the menu shows for `/gh clean`, in the host's own
+		 * confirmation shape (RiskConfirmation: title, description, an acknowledge
+		 * checkbox, two button labels). Confirm stays disabled until the box is
+		 * ticked — that is the "are you sure?", before the invocation is even sent.
+		 * The agent then re-establishes the exact list with `git clean -n` and asks
+		 * again: two gates, because this one names the risk and that one names the
+		 * files.
+		 */
+		function cleanGate() {
+			return {
+				title: "Remove untracked files?",
+				description: "Untracked files have no reflog and no stash entry — once removed they cannot be recovered. The agent will show the exact list (`git clean -n`) and ask again before removing anything.",
+				acknowledgeLabel: "I understand untracked files cannot be recovered",
+				cancelLabel: "Cancel",
+				confirmLabel: "Continue"
 			};
-			const next = info.next;
-			if (next !== void 0 && next !== null) add(next.args, next.why, next.what);
-			const ahead = info.ahead || 0;
-			const behind = info.behind || 0;
-			const staged = info.stagedFiles || 0;
-			const unstaged = info.unstagedFiles || 0;
-			const untracked = info.untrackedFiles || 0;
-			if (behind > 0 && ahead > 0) {
-				add("sync", ahead + " ahead, " + behind + " behind — diverged", "rebase your commits onto upstream and push (asks before any force)");
-			} else {
-				if (behind > 0) add("pull", behind + " behind " + (info.upstream ?? "upstream"), "update this branch from upstream");
-				if (ahead > 0) add("push", ahead + " ahead of " + (info.upstream ?? "upstream"), "push local commits to the remote");
-			}
-			if (staged > 0) add("commit", staged + " staged", "commit the staged changes");
-			if (unstaged > 0) add("commit", unstaged + " unstaged", "stage and commit the working changes");
-			if (unstaged === 0 && untracked > 0) add("commit", untracked + " untracked", "stage the new files and commit them");
-			const pr = info.pr;
-			if (pr !== void 0 && pr !== null && pr.number !== void 0) {
-				if (pr.state === "failing") add("checks " + pr.number, "checks failing on #" + pr.number, "watch the CI checks on pull request " + pr.number);
-				add("pr view " + pr.number, "open pull request #" + pr.number, "show pull request " + pr.number + " on GitHub");
-			} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && staged + unstaged + untracked === 0) {
-				add("pr", "branch is pushed and has no pull request", "open a pull request for this branch");
-			}
-			return subs.slice(0, 6);
 		}
 
 		/**
@@ -305,16 +300,29 @@ window.__ModuleLoader__.load({
 		 *  - clean workspaces stay quiet: arrows only when nonzero, no ✎ at 0
 		 *  - no upstream: arrows omitted entirely
 		 */
-		function formatGitSuffix(info) {
-			const parts = [];
+		/**
+		 * The upstream sync arrows (" ↑1 ↓2"), or "". Split out from the file
+		 * count so each rides the surface that OWNS it: the arrows belong to the
+		 * branch (they are the branch's standing against its upstream, and the
+		 * branch name's hover and compare link cover them), while ✎n belongs to the
+		 * count's names tooltip.
+		 */
+		function formatSync(info) {
 			const hasUpstream = info.ahead !== void 0 || info.behind !== void 0;
 			const files = (info.changedFiles || 0) + (info.untrackedFiles || 0);
-			if (hasUpstream && (files > 0 || info.ahead > 0 || info.behind > 0)) {
-				parts.push("\u2191" + (info.ahead || 0));
-				parts.push("\u2193" + (info.behind || 0));
-			}
-			if (files > 0) parts.push("\u270E" + files);
-			return parts.length > 0 ? " " + parts.join(" ") : "";
+			if (!hasUpstream || (files === 0 && !(info.ahead > 0) && !(info.behind > 0))) return "";
+			return " \u2191" + (info.ahead || 0) + " \u2193" + (info.behind || 0);
+		}
+
+		/** The ✎n file count (" ✎3"), or "". */
+		function formatFileCount(info) {
+			const files = (info.changedFiles || 0) + (info.untrackedFiles || 0);
+			return files > 0 ? " \u270E" + files : "";
+		}
+
+		/** Both halves, in chip order — kept for callers that want the whole suffix. */
+		function formatGitSuffix(info) {
+			return formatSync(info) + formatFileCount(info);
 		}
 
 		/**
@@ -544,9 +552,57 @@ window.__ModuleLoader__.load({
 		 */
 		const ACTION_STYLE = { flex: "none", marginLeft: "auto", marginRight: "8px", fontWeight: 500 };
 
-		/** The action badge: floated, weighted, and coloured by severity. */
-		function SessionGitBadge({ sessionId }) {
+		/**
+		 * The row's own run state, from the shell's standard kit.
+		 *
+		 * The renderer that assembles slots hands EVERY entry the sessions store as
+		 * a selector hook (`useSessions`) — the same kit that supplies
+		 * `useWorkspaces` — which is how a row can tell an idle session from one
+		 * mid-turn without the seam having to carry it. A shell that does not seed
+		 * that kit leaves the prop undefined: then we cannot know, and the badge
+		 * behaves exactly as it did before rather than guessing "idle".
+		 *
+		 * One helper and one call site, so the hook order is identical on every path
+		 * (the fallback is a plain function, never a hook).
+		 */
+		function useSessionRunning(useSessions, sessionId) {
+			const select = typeof useSessions === "function" ? useSessions : () => void 0;
+			return select((state) => state?.byId?.[sessionId]?.running) === true;
+		}
+
+		/**
+		 * Report the idle gate ONCE, the way the boot diagnostics report the seam and
+		 * the Tooltip primitive. Whether the shell actually handed a slot the
+		 * sessions store is invisible from anywhere else, and a gate that silently
+		 * never fires is indistinguishable from a gate that never needed to.
+		 */
+		let idleGateReported = false;
+		function reportIdleGate(present) {
+			if (idleGateReported) return;
+			idleGateReported = true;
+			console.info(
+				"[dsh-git-badge] session-row idle gate = " +
+					(present
+						? "on (the standard kit supplies useSessions)."
+						: "off (no useSessions prop) — the token cannot tell a running turn, so it shows as before.")
+			);
+		}
+
+		/**
+		 * The action badge: floated, weighted, and coloured by severity — and shown
+		 * only when the session is IDLE. A turn in flight is precisely when a git
+		 * suggestion is noise: the checkout is still moving and the agent has not
+		 * finished, so the action describes a state that is about to change. Nothing
+		 * about the action itself changes; the gate is the whole feature.
+		 *
+		 * The filter is on RENDER, not on the fetch: hiding the row must not take the
+		 * hover card's detail line down with it — both read the same cached status.
+		 */
+		function SessionGitBadge({ sessionId, useSessions }) {
 			const info = useGitStatus(sessionId === void 0 ? void 0 : { kind: "session", id: sessionId }, { pr: true });
+			const running = useSessionRunning(useSessions, sessionId);
+			reportIdleGate(typeof useSessions === "function");
+			if (running) return null;
 			if (sessionId === void 0 || info === void 0 || info.git !== true) return null;
 			const action = actionToken(info);
 			if (action === "") return null;
@@ -651,6 +707,64 @@ window.__ModuleLoader__.load({
 			return name;
 		}
 
+		/**
+		 * ONE commit line, shared by the branch hover and the PR token's hover so
+		 * the two cannot drift apart again: a fixed-width monospace hash cell, so
+		 * every description starts on the same column and the list reads as a
+		 * table, then `subject · age`. `sign` belongs to the branch hover — "+"
+		 * (only on this branch) or "−" (only on main); the PR list passes none,
+		 * because all of its commits are `base..HEAD`.
+		 *
+		 * The cell needs `display: inline-block` for `minWidth` to mean anything: an
+		 * inline span ignores it, which is exactly how the PR list came to render a
+		 * hash with NO gap at all — it reused the card's label style, whose
+		 * `minWidth` and `flex` only do anything inside a flex row.
+		 */
+		function CommitLine({ commit, sign = "" }) {
+			return react_jsx_runtime.jsxs("span", {
+				style: { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
+				children: [
+					react_jsx_runtime.jsx("span", {
+						style: {
+							color: "var(--dsw-alias-label-tertiary, #9ea7ad)",
+							fontFamily: "monospace",
+							display: "inline-block",
+							minWidth: "68px",
+							flex: "none"
+						},
+						children: sign + commit.hash
+					}),
+					commit.subject + (commit.when === "" ? "" : "  \u00B7 " + shortWhen(commit.when))
+				]
+			});
+		}
+
+		/**
+		 * The PR token's own hover body — the commits IN THIS PULL REQUEST
+		 * (`base..HEAD`), and nothing else: the token already says the number and
+		 * CI state, so the one question left is "what is in it?". Same line format
+		 * as the branch hover's commit list (see CommitLine — one renderer, so the
+		 * columns line up in both by construction), and the card's own width
+		 * behaviour: full-width lines, nowrap, ellipsis.
+		 */
+		function PrCommitsList({ info }) {
+			const commits = info?.prCommits;
+			if (!Array.isArray(commits) || commits.length === 0) {
+				return react_jsx_runtime.jsx("span", { style: CARD_CONTAINER, children: "no commits beyond the base branch" });
+			}
+			return react_jsx_runtime.jsxs("div", { style: CARD_CONTAINER, children: [
+				react_jsx_runtime.jsxs("div", {
+					style: { display: "flex", flexDirection: "column", gap: "2px", minWidth: 0 },
+					children: [
+						...commits.map((commit) => react_jsx_runtime.jsx(CommitLine, { commit }, commit.hash)),
+						(typeof info.prCommitsTotal === "number" && info.prCommitsTotal > commits.length
+							? "\u2026 and " + (info.prCommitsTotal - commits.length) + " more"
+							: null)
+					]
+				})
+			] });
+		}
+
 		const CARD_CONTAINER = {
 			display: "flex",
 			flexDirection: "column",
@@ -741,27 +855,11 @@ window.__ModuleLoader__.load({
 				if (value === void 0 || value === null || value === "") return;
 				rows.push(cardRow(label, value));
 			};
-			add("upstream", info?.upstream === void 0 ? "none configured" : info.upstream);
-			const ahead = info?.ahead || 0;
-			const behind = info?.behind || 0;
-			// The sync row speaks ONLY about the upstream it names: with no
-			// upstream configured there are no ahead/behind counts at all (no
-			// `# branch.ab` header), and falling back to 0/0 would claim "in
-			// sync" — a lie the upstream row directly contradicts. Omit it; the
-			// "none configured" row above carries the fact.
-			if (info?.upstream !== void 0) {
-				add("sync", ahead === 0 && behind === 0
-					? "in sync with upstream"
-					: "\u2191" + ahead + " \u2193" + behind);
-			}
-			// The merge-state row, in WORDS (deliberately not arrows — the sync
-			// row above already uses ↑↓ for the push axis, and two arrow pairs
-			// with different references would be read as one). "merge" is its
-			// label because it is the merge axis — the counterpart of "sync",
-			// the push axis — and it stays correct whatever the default branch
-			// is named. A BLOCKED verdict becomes the reason (review required,
-			// checks failing, draft) so a dead-end word names the next action;
-			// CLEAN stays silent — the action row already offers /gh merge.
+			// ONLY the merge axis, and it ALWAYS renders. The old upstream and sync
+			// rows spoke about the push axis (the branch's own remote), which the
+			// merge row subsumes: "1 ahead, 0 behind main" is the same fact stated
+			// against the branch that matters, in words rather than arrows. A row
+			// that can be absent is a row the reader has to reconstruct.
 			const pr = info?.pr;
 			const mergeParts = [];
 			if (pr !== void 0 && pr !== null && pr.number !== void 0) {
@@ -771,12 +869,15 @@ window.__ModuleLoader__.load({
 						: pr.state === "failing" ? "blocked: checks failing"
 						: "blocked");
 				} else if (pr.state === "failing") mergeParts.push("blocked: checks failing");
-				else if (pr.mergeState !== "CLEAN" && pr.review === "REVIEW_REQUIRED") mergeParts.push("blocked: review required");
+				else if (pr.mergeState === "CLEAN" || (pr.state === "passing" && pr.review === "APPROVED")) mergeParts.push("ready to merge");
+				else if (pr.review === "REVIEW_REQUIRED") mergeParts.push("blocked: review required");
+			} else {
+				mergeParts.push("no pull request");
 			}
 			if (info?.mainAhead !== void 0 || info?.mainBehind !== void 0) {
 				mergeParts.push((info.mainAhead || 0) + " ahead, " + (info.mainBehind || 0) + " behind main");
 			}
-			if (mergeParts.length > 0) add("merge", mergeParts.join(" \u00B7 "));
+			add("merge", mergeParts.join(" \u00B7 "));
 			const commits = info?.branchCommits;
 			if (Array.isArray(commits) && commits.length > 0) {
 				// Full-width block, not the label/value two-column row: commit lines
@@ -788,23 +889,9 @@ window.__ModuleLoader__.load({
 					react_jsx_runtime.jsxs("div", {
 						style: { display: "flex", flexDirection: "column", gap: "2px", minWidth: 0 },
 						children:
-							commits.map((commit) => react_jsx_runtime.jsxs("span", {
-								style: { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
-								children: [
-									// fixed-width monospace hash cell: every description starts
-									// on the same column, so the list reads as a table
-									react_jsx_runtime.jsx("span", {
-										style: {
-											color: "var(--dsw-alias-label-tertiary, #9ea7ad)",
-											fontFamily: "monospace",
-											display: "inline-block",
-											minWidth: "68px",
-											flex: "none"
-										},
-										children: (commit.sign === "+" ? "+" : commit.sign === "\u2212" ? "\u2212" : "") + commit.hash + ":"
-									}),
-									commit.subject + (commit.when === "" ? "" : "  \u00B7 " + shortWhen(commit.when))
-								]
+							commits.map((commit) => react_jsx_runtime.jsx(CommitLine, {
+								commit,
+								sign: commit.sign === "+" ? "+" : commit.sign === "\u2212" ? "\u2212" : ""
 							}, commit.hash))
 					}, "branch-commits")
 				);
@@ -891,11 +978,13 @@ window.__ModuleLoader__.load({
 				rows.push(cardRow(label, value));
 			};
 			// The "action" row — the top line, in the card's ordinary row layout:
-			// the gh skill invocation the checkout justifies, derived from the same
-			// state the /gh picker uses (first sub-action wins). Plain text, no
-			// affordance: the actionable surface is the (+) menu's /gh picker, and
-			// this row is the read-only pointer to it.
-			const topAction = ghSkillActions(data)[0];
+			// the SERVER's ranked suggestion, and nothing else. The client's
+			// extras (secondary picker entries) must never promote themselves into
+			// this line: when the server says there is nothing to do — clean and
+			// synced — the row is omitted, and "no suggestion" stays a suggestion.
+			// Plain text, no affordance: the actionable surface is the (+) menu's
+			// /gh picker, and this row is the read-only pointer to it.
+			const topAction = data.next;
 			if (topAction !== void 0) {
 				// git-comment convention: the invocation, two spaces, then "# "
 				// plus what it does
@@ -1011,12 +1100,18 @@ window.__ModuleLoader__.load({
 				// only (the node half rebuilt the URL from parsed parts); new tab,
 				// never navigating the conversation away.
 				const isLink = typeof detail?.compareUrl === "string" && detail.compareUrl.startsWith("https://");
+				// The sync arrows ride WITH the branch: they are the branch's standing
+				// against its upstream, so the same hover (lineage) and the same link
+				// (compare view, where the arrows are the diff) cover them. The ✎n
+				// count stays its own surface — it answers a different question.
+				const sync = formatSync(info);
+				const label = info.branch + sync;
 				const branch = isLink
 					? react_jsx_runtime.jsx("a", {
 						href: detail.compareUrl,
 						target: "_blank",
 						rel: "noopener noreferrer",
-						"aria-label": "Compare " + info.branch + " with main on GitHub",
+						"aria-label": "Compare " + info.branch + " with main on GitHub" + (sync === "" ? "" : ", " + (info.ahead || 0) + " ahead and " + (info.behind || 0) + " behind upstream"),
 						onPointerEnter: () => { setHovered(true); setBranchLinkHover(true); },
 						onPointerLeave: () => setBranchLinkHover(false),
 						onFocus: () => { setHovered(true); setBranchLinkHover(true); },
@@ -1026,12 +1121,12 @@ window.__ModuleLoader__.load({
 							textDecoration: branchLinkHover ? "underline" : "none",
 							cursor: "pointer"
 						},
-						children: info.branch
+						children: label
 					})
 					: react_jsx_runtime.jsx("span", {
 						onPointerEnter: () => setHovered(true),
 						style: { cursor: "default" },
-						children: info.branch
+						children: label
 					});
 				if (Tooltip === void 0 || detail === void 0 || detail === null) {
 					// mid-fetch the branch shows plain; the lineage tooltip is
@@ -1051,10 +1146,12 @@ window.__ModuleLoader__.load({
 			// either triggers it once — and degrades to a plain count on a shell
 			// without the Tooltip primitive.
 			const countHover = (() => {
+				// ✎n only: the sync arrows moved to the branch's surface above
+				const countText = formatFileCount(info);
 				const count = react_jsx_runtime.jsx("span", {
 					onPointerEnter: () => setHovered(true),
 					style: { cursor: "default" },
-					children: formatGitSuffix(info)
+					children: countText
 				});
 				const hasNames = (Array.isArray(detail?.untrackedNames) && detail.untrackedNames.length > 0)
 					|| (Array.isArray(detail?.unstagedNames) && detail.unstagedNames.length > 0);
@@ -1070,6 +1167,61 @@ window.__ModuleLoader__.load({
 			})();
 			const prToken = formatPrToken(info);
 			const prUrl = prLinkUrl(info);
+			// The PR token, with its own hover: the commits IN THIS PR (see
+			// PrCommitsList). Built here so the link/plain cases and the tooltip
+			// compose once instead of nesting a third conditional in the children.
+			// The token is its OWN detail gate: resting on it (or focusing it)
+			// enables the same `detail=1` fetch the mark and the branch do. Without
+			// that, a pointer going straight to the token had rested on nothing that
+			// fetches, so `prCommits` was never requested and this hover could not
+			// open at all — the data it renders is detail-only.
+			const prTokenHover = (() => {
+				const token = prUrl === void 0
+					? react_jsx_runtime.jsx("span", {
+						// 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),
+						onPointerEnter: () => setHovered(true),
+						style: { cursor: "default" },
+						children: prToken
+					})
+					: react_jsx_runtime.jsx("a", {
+						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: () => { setHovered(true); setLinkHover(true); },
+						onPointerLeave: () => setLinkHover(false),
+						onFocus: () => { setHovered(true); setLinkHover(true); },
+						onBlur: () => setLinkHover(false),
+						children: prToken
+					});
+				if (Tooltip === void 0 || detail === void 0 || detail === null
+					|| !Array.isArray(detail.prCommits) || detail.prCommits.length === 0) {
+					return token;
+				}
+				return react_jsx_runtime.jsx(Tooltip, {
+					side: "top",
+					maxWidth: 480,
+					label: () => react_jsx_runtime.jsx(PrCommitsList, { info: detail }),
+					children: token
+				});
+			})();
 			const chip = react_jsx_runtime.jsxs("span", {
 				style: {
 					display: "inline-flex",
@@ -1103,43 +1255,7 @@ window.__ModuleLoader__.load({
 						branchHover,
 						react_jsx_runtime.jsx("span", { key: "text", children: text }),
 					countHover,
-					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
-								}),
+					prTokenHover,
 					/**
 					 * The seam-absent notice: the market-install notification for the
 					 * state a blocked postinstall leaves behind — chip working, sidebar
@@ -1424,7 +1540,12 @@ window.__ModuleLoader__.load({
 										info = await fetch("/api/git-badge?" + query).then((r) => r.json());
 									}
 									const actions = ghSkillActions(info);
-									return actions.map((action) => ({ label: "/gh " + action.args, detail: action.why, args: action.args }));
+									return actions.map((action) => ({
+										label: "/gh " + action.args,
+										detail: action.why,
+										args: action.args,
+										...action.danger === true ? { confirmation: cleanGate() } : {}
+									}));
 								} catch (error) {
 									console.error("[dsh-git-badge] /gh options failed:", error);
 									return [];
@@ -1667,7 +1788,7 @@ window.__ModuleLoader__.load({
 		// 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, formatCheckoutDetail, worktreeDetail, actionToken, ghSkillActions, moveCategory };
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken, ghSkillActions, cleanGate, moveCategory };
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -95,6 +95,8 @@ const config = {
 	fetchTimeoutMs: 8000,
 	/** minimum interval between background fetches per toplevel */
 	fetchTtlMs: 60000,
+	/** how long a resolved default-branch name is trusted (per toplevel) */
+	defaultBranchTtlMs: 60000,
 	/** fs-event burst collapse window */
 	debounceMs: 200,
 	/**
@@ -130,8 +132,16 @@ const config = {
 	 * process — see the PR region.
 	 */
 	prStatus: "auto",
-	/** minimum interval between forge refreshes per repository */
-	prTtlMs: 90000,
+	/**
+	 * Minimum interval between forge refreshes per repository. It must stay BELOW
+	 * the client's idle poll (FALLBACK_POLL_MS, 60s in lib/client.js): the refresh
+	 * is request-driven, so a TTL longer than that poll silently suppresses every
+	 * OTHER request — and a pull request that appears on the forge with no local
+	 * git event to announce it then waits out TTL + poll before it shows. At 90s
+	 * that worst case was ~2.5 minutes; 20s bounds it at roughly one poll, for up
+	 * to one `gh pr view` per open chip per minute.
+	 */
+	prTtlMs: 20000,
 	/**
 	 * 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
@@ -210,6 +220,32 @@ const GIT_DEGRADED = { git: false, error: "git unavailable (timeout or failure)"
  * auto-fetch), with a TTL rather than a timer: fetch only happens when
  * someone is actually looking at the badge.
  */
+/**
+ * toplevel -> { at, value } for the repository's default branch name ("main"),
+ * resolved from `refs/remotes/origin/HEAD`. Read on the HOT path and refreshed
+ * out of band, exactly like the fetch: a status call must never pay a process
+ * for it, so the first request after a cache miss simply answers without the
+ * flag and the next one carries it.
+ */
+const defaultBranchState = new Map();
+
+/** The cached default branch, kicking a refresh when stale. Never throws. */
+function defaultBranchFor(toplevel, notify) {
+	const now = Date.now();
+	const cached = defaultBranchState.get(toplevel);
+	if (cached === void 0 || now - cached.at >= config.defaultBranchTtlMs) {
+		// out of band: this answer is served from what we already know
+		void (async () => {
+			const out = await runGit(toplevel, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+			const name = out.stdout === null ? "" : out.stdout.trim().replace(/^origin\//u, "");
+			const previous = defaultBranchState.get(toplevel)?.value;
+			defaultBranchState.set(toplevel, { at: Date.now(), value: name === "" ? void 0 : name });
+			if (previous !== defaultBranchState.get(toplevel).value) notify?.();
+		})();
+	}
+	return cached?.value;
+}
+
 /** lastFetchAt per toplevel; in-flight promise per toplevel collapses races. */
 const fetchState = new Map();
 
@@ -730,7 +766,7 @@ function nextOrder() {
  *
  * @returns {{ args: string, command: string|undefined, why: string, what: string } | null}
  */
-function nextStep(info) {
+function nextStepRules(info) {
 	if (info === void 0 || info === null || info.git !== true) return null;
 	const unmerged = info.unmergedFiles || 0;
 	const plural = (n) => (n === 1 ? "" : "s");
@@ -786,15 +822,80 @@ function nextStep(info) {
 	if (pr !== void 0 && pr.number !== void 0 && pr.state === "failing") {
 		add("checks", `checks ${pr.number}`, `checks failing on #${pr.number}`, "watch the CI checks on pull request " + pr.number, `gh pr checks ${pr.number} --watch`);
 	}
-	if (rules.length === 0) return null;
+
+	// STANDING options: never ranked, never the primary suggestion — they are
+	// things you may do, not things the checkout is asking for. `pr view` exists
+	// whenever a pull request does; `pr` (create) only for a pushed branch that
+	// is not the default; `clean` last and flagged, because a destructive verb
+	// whose intent git status cannot reveal must never be suggested.
+	const standing = [];
+	if (pr !== void 0 && pr.number !== void 0) {
+		standing.push({
+			args: `pr view ${pr.number}`,
+			why: `open pull request #${pr.number}`,
+			what: `show pull request ${pr.number} on GitHub`
+		});
+	} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && dirty === 0 && info.defaultBranch !== true) {
+		standing.push({ args: "pr", why: "branch is pushed and has no pull request", what: "open a pull request for this branch" });
+	}
+	if (untracked > 0) {
+		standing.push({
+			args: "clean",
+			why: `${untracked} untracked file${plural(untracked)}`,
+			what: "remove untracked files — lists them and asks first",
+			danger: true
+		});
+	}
 
 	const order = nextOrder();
 	const rank = (cat) => {
 		const at = order.indexOf(cat);
 		return at === -1 ? order.length : at;
 	};
-	const [top] = [...rules].sort((a, b) => rank(a.cat) - rank(b.cat));
-	return { args: top.args, command: top.command, why: top.why, what: top.what };
+	const ranked = [...rules].sort((a, b) => rank(a.cat) - rank(b.cat)).slice(0, 5);
+	return { ranked, standing };
+}
+
+/**
+ * Every action the checkout justifies, in order — the ONE list both surfaces
+ * render: the card shows the primary entry, the (+) picker lists them all.
+ *
+ * The server owns the whole list because both halves previously carried their
+ * own copy of these conditions and drifted: the card promoted a client-only
+ * extra into its action row, and `/gh pr` was offered on the default branch.
+ * One authority, one list, no reconciliation.
+ *
+ * Exactly one entry can be `primary` (the top RANKED rule) or none at all —
+ * a clean, synced checkout has actions (look at the PR, clean up) but no
+ * suggestion, because "no suggestion" is also a suggestion.
+ *
+ * @returns {{ actions: Array<{args, why, what, command?, danger?, primary?}>, next: object|null }}
+ */
+function nextActions(info) {
+	const built = nextStepRules(info);
+	if (built === null) return { actions: [], next: null };
+	const { ranked, standing } = built;
+	const actions = [
+		...ranked.map((rule, index) => ({
+			args: rule.args,
+			why: rule.why,
+			what: rule.what,
+			...(rule.command === void 0 ? {} : { command: rule.command }),
+			...(index === 0 ? { primary: true } : {})
+		})),
+		...standing
+	];
+	const primary = actions.find((action) => action.primary === true) ?? null;
+	return { actions, next: primary };
+}
+
+/**
+ * The single ranked suggestion, or null — the card's action row and the legacy
+ * shape. It is the primary entry of {@link nextActions}, never a standing
+ * option.
+ */
+function nextStep(info) {
+	return nextActions(info).next;
 }
 
 /**
@@ -897,6 +998,15 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		ahead: parsed.ahead,
 		behind: parsed.behind
 	};
+	// Is this the repository's DEFAULT branch? main/master with no pull request
+	// is that branch's normal state, and "open a pull request for this branch" is
+	// nonsense there, so the surfaces suppress it. Cached and refreshed out of
+	// band: the flag may be absent on the very first read, present on the next.
+	const defaultBranch = defaultBranchFor(toplevel, notifyChange);
+	if (defaultBranch !== void 0 && defaultBranch === parsed.branch) info.defaultBranch = true;
+	// Resolved inside the detail block; the PR-token hover below reuses it, so it
+	// is declared here rather than scoped to that block.
+	let baseRef = null;
 	if (wantDetail) {
 		// The ✎n NAMES — the one part of the count the numbers cannot answer
 		// ("what are these?"). Hover-gated with the rest of detail=1, so no
@@ -944,7 +1054,7 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		if (remoteUrl.stdout !== null && remoteUrl.stdout.trim() !== "") {
 			info.repoUrl = remoteToWebUrl(remoteUrl.stdout);
 		}
-		const baseRef = probeMain.stdout !== null && probeMain.stdout.trim() !== ""
+		baseRef = probeMain.stdout !== null && probeMain.stdout.trim() !== ""
 			? "origin/main"
 			: probeMaster.stdout !== null && probeMaster.stdout.trim() !== "" ? "origin/master" : null;
 		if (baseRef !== null && info.repoUrl !== void 0) {
@@ -1009,8 +1119,28 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
 		if (pr !== void 0) info.pr = pr;
 	}
-	const next = nextStep(info);
+	if (baseRef !== null && info.pr !== void 0 && info.pr !== null && info.pr.number !== void 0
+		&& info.pr.open !== false && (info.mainAhead || 0) > 0) {
+		// The PR's OWN commits (base..HEAD) — the token's hover answers "what is in
+		// this pull request", so it lists exactly that: not the branch's recent
+		// history, nothing else. Hover-gated with the rest of detail=1, and the
+		// total is the ahead count already computed above (no second rev-list).
+		const prOut = await runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", baseRef + "..HEAD"]);
+		if (prOut.stdout !== null && prOut.stdout.trim() !== "") {
+			info.prCommits = prOut.stdout.trim().split("\n").map((line) => {
+				const [hash, subject, when] = line.split("\t");
+				return { hash, subject: subject ?? "", when: when ?? "" };
+			}).filter((c) => c.hash !== void 0);
+			info.prCommitsTotal = info.mainAhead;
+		}
+	}
+	// The ranked suggestion rides EVERY response (it is pure derivation, and a
+	// sidebar row may one day use it instead of its own copy of these rules);
+	// the full action list is sent only for `pr=1`, the surfaces that have a
+	// picker, so a row's payload stays lean.
+	const { actions, next } = nextActions(info);
 	if (next !== null) info.next = next;
+	if (wantPr && actions.length > 0) info.actions = actions;
 	return info;
 }
 
@@ -1649,6 +1779,7 @@ export {
 	OPERATION_MARKERS,
 	operationMarker,
 	nextStep,
+	nextActions,
 	outerGitDir,
 	parseStatusV2,
 	parseWorktreeList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Git status badges for DeepSeek Harness: an input-row chip on every install, plus sidebar session-row badges (git status, PR/CI action tokens) after one manual step: `npx dsh-git-badge apply`, then restart dsh web. Event-driven freshness over SSE.",
   "type": "module",
   "main": "lib/index.js",

package/skill/gh/SKILL.md

@@ -87,6 +87,27 @@ unstaged / untracked / unmerged), plus any in-progress operation marker
   A session's cwd is fixed at creation, so this registration is the ONLY signal
   the badge has.
 
+- **`/gh clean [<path>...]`** — remove untracked files, and only with the user's
+  explicit yes for the exact list. It appears in the `/gh` menu whenever
+  untracked files exist, always last, behind the host's risk gate: picking it
+  opens a confirmation whose box must be ticked before the invocation is even
+  sent. That gate names the RISK, not the files — so the explicit paths and the
+  second yes below are still required. This is the one verb whose first step is a
+  DRY RUN, always:
+
+  1. `git clean -n -- <paths>` and quote its output back verbatim — the user is
+     approving that list, not the idea of cleaning;
+  2. ask; if the answer is anything but an unambiguous yes, stop and change
+     nothing;
+  3. `git clean -f -- <paths>` — named paths only.
+
+  Never `-x` (ignored files are often credentials), never `-d` (whole
+  directories), never a bare `git clean -f`, and never a path the user did not
+  name or approve. With no argument, list what `git clean -n` reports and ask
+  which paths to remove rather than picking for them. Untracked files have no
+  reflog and no stash entry: what this removes cannot be recovered, so a
+  mistaken cleanup is unrecoverable in a way a mistaken commit is not.
+
 - **`/gh order`** — reconfigure which action class the badge ranks first. The
   order lives in the `git-badge` settings namespace, edited in the UI at
   **Settings → Plugins → Git Badge** (an ordered list with up/down controls).
@@ -108,7 +129,8 @@ the `gh-pr` skill; hand off rather than improvise a lifecycle.
 ## Hard rules
 
 - Never `git reset --hard`, `git clean`, `git checkout -- .`, `git push
-  --force` (plain), or any history rewrite without an explicit user yes.
+  --force` (plain), or any history rewrite without an explicit user yes —
+  `/gh clean`'s dry run and verbatim quote come before any `git clean -f`.
 - `GIT_TERMINAL_PROMPT=0` on network commands so a missing credential fails
   fast instead of hanging.
 - One operation per invocation; report the outcome, then stop.