dsh-git-badge 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -10,6 +10,37 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-15
+
+### Added
+
+- **A "next" row at the top of the chip's hover card.** The node half derives
+  the single highest-priority next step from fields the status response already
+  carries — a paused operation and its resume command, `git pull --ff-only`
+  when behind, `git push -u origin <branch>` when no upstream exists on a dirty
+  branch, `git push` when ahead, a conservative commit command when dirty
+  (`add -p` for unstaged work, `-A` only for untracked-only changes, which
+  `add -p` cannot see), and `gh pr checks <n> --watch` when CI fails. Each
+  suggestion carries its reason, and the command is a click-to-copy chip — it
+  runs in the user's own terminal, never through dsh. Clean, synced, nothing
+  failing → no row. Pure derivation: no extra git invocations, and the ranking
+  is unit-tested in the node suite.
+
+## [0.13.0] - 2026-09-15
+
+### Added
+
+- **A visible seam-absent notice on the input chip.** When `allowBuilds` keeps
+  the postinstall from patching, a market install lands chip-working but
+  sidebar-off with no message anywhere — dshmarket cannot see host files, and
+  the old hint was a hover tooltip nobody finds. Now, once the 5-second boot
+  grace proves the seam is genuinely absent, the chip shows
+  *sidebar badges off — run `npx dsh-git-badge apply`* with a dismiss **×**.
+  The notice is always true and self-resolving: apply + restart makes the seam
+  declare and it never renders again. The × means *stop asking this boot* —
+  dismissal is session-scoped, so a seam that is still absent asks again at the
+  next boot, and the long-form explanation stays on the chip's hover tooltip.
+
 ## [0.12.0] - 2026-09-15
 
 ### Removed

package/lib/client.js

@@ -50,6 +50,11 @@ window.__ModuleLoader__.load({
 			primitives = null;
 		}
 		const Tooltip = primitives === null ? void 0 : primitives.Tooltip;
+		// The shell's pull-down primitive (what the input-area selectors use) and
+		// its candidate ranker. Same guarded require as Tooltip: a shell without
+		// them loses the pull-down affordances, never the badges.
+		const Menu = primitives === null ? void 0 : primitives.Menu;
+		const rankByName = primitives === null ? void 0 : primitives.rankByName;
 
 		/** Module-level git-status cache. Entries are invalidated by SSE events, never by age. */
 		const GIT_CACHE = new Map();
@@ -225,6 +230,94 @@ window.__ModuleLoader__.load({
 			return "ok";
 		}
 
+		/**
+		 * The git action list both actionable surfaces render — the `!` trigger
+		 * menu in the input and the branch pull-down on the chip. State-filtered:
+		 * the server's `next` suggestion leads, then only actions the current
+		 * status justifies. Deduped by command (the next step already covers one
+		 * of these when it agrees) and capped, because a menu of twelve is a
+		 * reference manual, not an action menu.
+		 */
+		function buildActions(info) {
+			if (info === void 0 || info === null || info.git !== true) return [];
+			const actions = [];
+			const seen = new Set();
+			const add = (command, why) => {
+				if (typeof command !== "string" || command === "" || seen.has(command)) return;
+				seen.add(command);
+				actions.push({ name: command, label: command, description: why, command, why });
+			};
+			const next = info.next;
+			if (next !== void 0 && next !== null && typeof next.command === "string") {
+				add(next.command, next.why);
+			}
+			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) add("git pull --ff-only", behind + " behind " + (info.upstream ?? "upstream"));
+			if (ahead > 0) add("git push", ahead + " ahead of " + (info.upstream ?? "upstream"));
+			if (staged > 0) add("git commit", staged + " staged");
+			if (unstaged > 0) add("git add -p && git commit", unstaged + " unstaged");
+			if (unstaged === 0 && untracked > 0) add("git add -A && git commit", untracked + " untracked");
+			if ((info.stashCount || 0) > 0) add("git stash list", info.stashCount + " stashed");
+			const pr = info.pr;
+			if (pr !== void 0 && pr !== null && pr.number !== void 0) {
+				if (pr.state === "failing") add("gh pr checks " + pr.number + " --watch", "checks failing on #" + pr.number);
+				add("gh pr view " + pr.number, "open pull request #" + pr.number);
+			} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && staged + unstaged + untracked === 0) {
+				add("gh pr create", "branch is pushed and has no pull request");
+			}
+			return actions.slice(0, 6);
+		}
+
+		/** The input text a picked action becomes: the command, then why as a comment. */
+		function actionText(action) {
+			return "!" + action.command + " # " + action.why;
+		}
+
+		/**
+		 * The /gh picker's sub-actions — the skill invocations the checkout
+		 * justifies, most urgent first. Same ranking the server's nextStep uses,
+		 * but spoken in skill arguments; the generic "next" entry is skipped when
+		 * a specific rule already names the same situation (its why would be
+		 * identical, and two rows for one fact is noise).
+		 */
+		function ghSkillActions(info) {
+			if (info === void 0 || info === null || info.git !== true) return [];
+			const subs = [];
+			const seen = new Set();
+			const add = (args, why) => {
+				if (seen.has(args)) return;
+				seen.add(args);
+				subs.push({ args, why });
+			};
+			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) add("pull", behind + " behind " + (info.upstream ?? "upstream"));
+			if (ahead > 0) add("push", ahead + " ahead of " + (info.upstream ?? "upstream"));
+			if (staged > 0) add("commit", staged + " staged");
+			if (unstaged > 0) add("commit", unstaged + " unstaged");
+			if (unstaged === 0 && untracked > 0) add("commit", untracked + " untracked");
+			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);
+				add("pr view " + pr.number, "open pull request #" + pr.number);
+			} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && staged + unstaged + untracked === 0) {
+				add("pr", "branch is pushed and has no pull request");
+			}
+			const next = info.next;
+			if (next !== void 0 && next !== null && typeof next.command === "string"
+				&& !subs.some((entry) => entry.why === next.why)) {
+				add("next", next.why);
+			}
+			return subs.slice(0, 6);
+		}
+
 		/**
 		 * Mark fill per status, from the app's own semantic tokens so BOTH surfaces
 		 * follow light/dark and custom themes — which a hardcoded emoji cannot do.
@@ -617,6 +710,66 @@ window.__ModuleLoader__.load({
 		const CARD_LABEL = { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", minWidth: "62px" };
 		const CARD_VALUE = { minWidth: 0, overflowWrap: "anywhere" };
 
+		/**
+		 * The "next" row's body: why, then the command as a click-to-copy chip.
+		 * Clipboard-only by design — no server call, no path exposure; the command
+		 * lands in the user's clipboard to run in their own terminal. `navigator.
+		 * clipboard` needs a user gesture (a click is one) and a secure context
+		 * (localhost is one); a denied write degrades to a no-op and the command
+		 * is still readable as text.
+		 */
+		function NextStepRow({ next }) {
+			const [copied, setCopied] = react.useState(false);
+			const copy = () => {
+				if (typeof next.command !== "string") return;
+				try {
+					void navigator.clipboard.writeText(next.command).then(
+						() => {
+							setCopied(true);
+							setTimeout(() => setCopied(false), 1500);
+						},
+						() => void 0,
+					);
+				} catch {
+					void 0;
+				}
+			};
+			return react_jsx_runtime.jsxs(
+				"span",
+				{
+					style: { ...CARD_VALUE, display: "inline-flex", alignItems: "center", gap: "6px", flexWrap: "wrap" },
+					children: [
+						react_jsx_runtime.jsx("span", { children: next.why }),
+						typeof next.command === "string"
+							? react_jsx_runtime.jsx(
+									"button",
+									{
+										"aria-label": "Copy command: " + next.command,
+										title: "Copy command: " + next.command,
+										onClick: copy,
+										style: {
+											cursor: "pointer",
+											color: "inherit",
+											background: "none",
+											border: "1px solid var(--dsw-alias-border-secondary, #d0d7de)",
+											borderRadius: "4px",
+											fontSize: "11px",
+											lineHeight: "16px",
+											padding: "0 5px",
+											flex: "none",
+											fontFamily: "monospace"
+										},
+										children: copied ? "copied" : next.command
+									},
+									"cmd"
+								)
+							: null
+					]
+				},
+				"next-body"
+			);
+		}
+
 		/**
 		 * Hover card body for the input chip — INPUT CHIP ONLY. Pure presentation
 		 * over fields the status response already carries, plus the `detail=1`
@@ -640,6 +793,18 @@ window.__ModuleLoader__.load({
 					}, label)
 				);
 			};
+			// The "next" row — the node half's single highest-priority suggestion,
+			// { command, why } or absent (clean + synced + nothing failing). Clicking
+			// copies the command; it is the one actionable affordance the card
+			// carries, and it costs no server surface: the command runs in the
+			// user's own terminal, never here. Per-open state: the copied ack
+			// resets the next time the card opens, which is the honest lifetime for it.
+			const next = data.next;
+			if (next !== void 0 && next !== null && typeof next.why === "string") {
+				rows.push(
+					react_jsx_runtime.jsxs(NextStepRow, { next }, "next")
+				);
+			}
 			add("branch", info.branch);
 			add("upstream", info.upstream === void 0 ? "none configured" : info.upstream);
 			if (info.ahead !== void 0 || info.behind !== void 0) {
@@ -703,6 +868,16 @@ window.__ModuleLoader__.load({
 		 */
 		let seamHint = null;
 
+		/**
+		 * Dismissal of the seam-absent notice, deliberately MODULE-level rather
+		 * than component state: a useState flag would un-dismiss when the chip
+		 * remounts (a sidebar toggle, a route change), and the × the user just
+		 * clicked would silently stop meaning anything. Session-scoped on
+		 * purpose — it resets at the next boot, so a seam that is STILL absent
+		 * asks again, while one fixed by apply + restart never nags at all.
+		 */
+		let seamNoticeDismissed = false;
+
 		function ComposerGitChip({ 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
@@ -715,8 +890,42 @@ window.__ModuleLoader__.load({
 			// 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);
+			// seamHint is module state set once, 5s after boot; dismissing it needs a
+			// re-render that no fetch will schedule, so the × bumps a counter here.
+			const [, bumpNotice] = react.useState(0);
+			const seamNotice = seamHint !== null && !seamNoticeDismissed ? seamHint : null;
+			// The branch pull-down (model-selection pattern): a chevron opens the
+			// shell Menu of state-filtered git actions; picking COPIES the command —
+			// the composer has no public insert API (see the trigger source in
+			// apply() for the insertion-capable surface), so this surface's contract
+			// is paste-and-send, the same one the hover card's chip has always had.
+			const [menuOpen, setMenuOpen] = react.useState(false);
+			const [copied, setCopied] = react.useState(false);
 			const detail = useGitStatus(target, { pr: true, detail: true, enabled: hovered });
 			if (info === void 0 || info.git !== true) return null;
+			const actions = buildActions({ ...info, ...(detail ?? {}) });
+
+			// The status mark wrapped in the chip's hover card — the card's ONLY
+			// anchor. Pointer rest here (and only here) enables the detail=1 fetch,
+			// so the extras are paid for exactly when the card that can render them
+			// is about to open. Defined inside the component: it closes over the
+			// hovered state that gates the detail fetch.
+			const hoverableMark = (() => {
+				const mark = react_jsx_runtime.jsx("span", {
+					onPointerEnter: () => setHovered(true),
+					style: { display: "inline-flex", alignItems: "center", flex: "none", cursor: "default" },
+					children: react_jsx_runtime.jsx(StatusMark, { info })
+				});
+				if (Tooltip === void 0) return mark;
+				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: mark
+				});
+			})();
 			// 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
@@ -738,16 +947,83 @@ window.__ModuleLoader__.load({
 					whiteSpace: "nowrap",
 					cursor: "default"
 				},
-				// the only in-product message a market user gets when the seam is
-				// absent: hover the chip you CAN see to learn the one command that
-				// turns on the rows you cannot. null until the delayed check in
-				// apply() proves the seam never appeared.
+				// the long-form explanation, on hover; the inline seam-notice below is
+				// the visible channel (its text is the short form, its title this).
+				// null until the delayed check in apply() proves the seam never
+				// appeared.
 				title: seamHint === null ? undefined : seamHint,
-				// 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 }),
+					// The hover card belongs to the STATUS SYMBOL, not the badge: the
+					// circle is the "what does this colour mean" element, and a card
+					// opening sideways from a hover on the branch text got in the way of
+					// the very pull-down this row now carries. The detail fetch
+					// (enabled: hovered) follows the same pointer, so nothing pays for
+					// extras the card no longer shows. The seam-absent native title
+					// stays on the whole chip — it is about the badge, not the mark.
+					hoverableMark,
+
+					Menu === void 0 || actions.length === 0
+						? null
+						: react_jsx_runtime.jsx(Menu, {
+							key: "actions",
+							open: menuOpen,
+							onClose: () => setMenuOpen(false),
+							items: actions.map((action) => ({ id: action.command, label: action.label, description: action.description })),
+							onSelect: (picked) => {
+								setMenuOpen(false);
+								// the shell may hand back the id or the whole item — take either
+								const id = typeof picked === "string" ? picked : picked?.id;
+								const action = actions.find((entry) => entry.command === id);
+								console.info("[dsh-git-badge] pull-down pick:", id, "->", action === void 0 ? "NOT FOUND" : actionText(action));
+								if (action === void 0) return;
+								try {
+									void navigator.clipboard.writeText(actionText(action)).then(() => {
+										setCopied(true);
+										setTimeout(() => setCopied(false), 1200);
+									}, () => void 0);
+								} catch {
+									void 0;
+								}
+							},
+							align: "start",
+							portal: true,
+							anchor: react_jsx_runtime.jsxs(
+								"button",
+								{
+									type: "button",
+									"aria-haspopup": "menu",
+									"aria-expanded": menuOpen,
+									"aria-label": "Git actions for " + info.branch,
+									title: copied ? "copied — paste in your terminal" : "git actions",
+									onClick: () => setMenuOpen((value) => !value),
+									// the metrics of the row's own selectors (the access/model
+									// pull-downs): inline-flex, centered on the 24px line, no
+									// border or padding, icon flex-none so the chevron reads as an
+									// affordance, not a second label
+									style: {
+										cursor: "pointer",
+										color: "inherit",
+										background: "none",
+										border: "none",
+										display: "inline-flex",
+										alignItems: "center",
+										justifyContent: "center",
+										fontSize: "12px",
+										lineHeight: "24px",
+										padding: "0",
+										flex: "none"
+									},
+									children: [
+										copied
+											? "\u2713"
+											: (primitives !== null && primitives.IconChevronDownOutline14 !== void 0
+												? react_jsx_runtime.jsx(primitives.IconChevronDownOutline14, {})
+												: "\u25BE")
+									]
+								},
+								"actions-anchor"
+							)
+						}),
 					react_jsx_runtime.jsx("span", { key: "text", children: text }),
 					prToken === ""
 						? null
@@ -786,27 +1062,82 @@ window.__ModuleLoader__.load({
 									onBlur: () => setLinkHover(false),
 									children: prToken
 								}),
+					/**
+					 * The seam-absent notice: the market-install notification for the
+					 * state a blocked postinstall leaves behind — chip working, sidebar
+					 * rows structurally off, nothing patched, nothing to restart INTO.
+					 * It is only ever TRUE (seamHint is set 5s after boot, only after
+					 * the composed graph is given its chance), and it is self-resolving:
+					 * apply + restart makes the seam declare, and this never renders
+					 * again. That is what distinguishes it from the old restart notice,
+					 * which outlived the restart it asked for. Dismissal is a session
+					 * value (see seamNoticeDismissed), so the × means "stop asking this
+					 * boot", never "stop asking forever".
+					 */
+					seamNotice === null
+						? null
+						: react_jsx_runtime.jsxs(
+								"span",
+								{
+									style: {
+										display: "inline-flex",
+										alignItems: "center",
+										gap: "6px",
+										paddingLeft: "6px",
+										borderLeft: "1px solid var(--dsw-alias-border-secondary, #d0d7de)",
+										whiteSpace: "normal",
+										maxWidth: "320px"
+									},
+									children: [
+										react_jsx_runtime.jsx(
+											"span",
+											{
+												title: seamHint,
+												children: "sidebar badges off — run `npx dsh-git-badge apply`"
+											},
+											"explain"
+										),
+										react_jsx_runtime.jsx(
+											"button",
+											{
+												"aria-label": "Dismiss the sidebar-badges notice (returns next boot while the seam is absent)",
+												onClick: () => {
+													seamNoticeDismissed = true;
+													bumpNotice((n) => n + 1);
+												},
+												style: {
+													cursor: "pointer",
+													color: "inherit",
+													background: "none",
+													border: "1px solid var(--dsw-alias-border-secondary, #d0d7de)",
+													borderRadius: "4px",
+													fontSize: "11px",
+													lineHeight: "18px",
+													padding: "0 6px",
+													flex: "none"
+												},
+												children: "×"
+											},
+											"dismiss"
+										)
+									]
+								},
+								"seam-notice"
+							),
 				]
 			});
-			// 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
+			// No Tooltip primitive (a shell that does not seed it): the mark renders
+			// bare and the badge still works — 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
-			});
+			return chip;
 		}
+
 		//#endregion
 
 		// `workspaces` is no longer required: both surfaces target an id and the
 		// node half resolves the workspace, so the client never needs a service
 		// lookup. Fewer declared services also means fewer ways to fail to load.
-		const inject = ["slots"];
+		const inject = ["slots", "inputTriggers"];
 
 		/**
 		 * Register the badge into the seams. The seam owner hands each entry the row
@@ -814,6 +1145,93 @@ window.__ModuleLoader__.load({
 		 * deliberately ignores the cwd it may also be given.
 		 */
 		function apply(ctx) {
+			// The /gh command contribution (the (+) commands menu): the state-aware
+			// entry point to the gh skill. available() gates on the cached git
+			// status; options() lists only the sub-actions the checkout justifies;
+			// onSelect SENDS the skill invocation ("/gh push") as a conversation
+			// message — the agent executes the skill under its own approval flow,
+			// and the shell consumes the /gh token afterwards. This is the one
+			// blessed route from a menu pick to a git action; it is a SEND, which
+			// is why the destructive-step confirmation lives in the skill text.
+			// Guarded: a host without commandUi loses the menu entry, never the
+			// badges.
+			if (typeof ctx.inject === "function") {
+				ctx.inject(["commandUi", "sessions"], (scope) => {
+					try {
+					scope.effect(() => scope.commandUi.register({
+						name: "gh",
+						// the contract calls description() as a FUNCTION at menu-build
+						// time (candidates: contribution.description()) — a string throws
+						// TypeError on every candidates pass and kills the whole menu,
+						// (+) button included
+						description: () => "git/gh actions for this checkout — push, pull, pr, commit, checks",
+						available: (session) => {
+							// called during the host's menu build — a throw here kills the
+							// whole menu, so it degrades to "hidden" instead
+							try {
+								const query = targetQuery({ kind: "session", id: session?.sessionId }, { pr: true });
+								return query !== void 0 && GIT_CACHE.get(query)?.data?.git === true;
+							} catch (error) {
+								console.error("[dsh-git-badge] /gh available failed:", error);
+								return false;
+							}
+						},
+						ui: {
+							options: async (session, signal) => {
+								try {
+									const sessionId = session?.sessionId;
+									if (sessionId === void 0) return [];
+									const query = targetQuery({ kind: "session", id: sessionId }, { pr: true });
+									if (query === void 0) return [];
+									// cache-first: the badge's own knowledge opens the picker
+									// instantly; a cold session pays one status fetch.
+									let info = GIT_CACHE.get(query)?.data;
+									if (info === void 0 || info === null) {
+										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 }));
+								} catch (error) {
+									console.error("[dsh-git-badge] /gh options failed:", error);
+									return [];
+								}
+							},
+							onSelect: async (option, session) => {
+								// Send the invocation: the message lands in the transcript
+								// and the agent executes the gh skill — the approval flow
+								// for anything destructive is the agent's, per the skill
+								// text. The prompt path is the conversation's own: the
+								// sessions service binds a sessionId to { session } and
+								// binding.session.prompt(content, "queue") is exactly what
+								// the composer's send() calls.
+								const sessionId = session?.sessionId;
+								const sessions = typeof scope.sessions === "function" ? scope.sessions() : scope.sessions;
+								const binding = sessions?.binding?.(sessionId);
+								const target = binding?.session;
+								if (target?.prompt === void 0) {
+									console.error("[dsh-git-badge] /gh: no prompt path (binding missing or session-less)", {
+										sessionId,
+										hasSessions: sessions !== void 0,
+										hasBinding: binding !== void 0
+									});
+									return;
+								}
+								const result = await target.prompt([{ type: "text", text: "/gh " + option.args }], "queue");
+								if (result !== void 0 && result !== null && result.ok === false) {
+									console.error("[dsh-git-badge] /gh submit refused:", result.error);
+								}
+							}
+						}
+					}), "dsh-git-badge: /gh contribution");
+					} catch (error) {
+						// a failed registration must degrade to "no /gh entry", never to
+						// a broken commands menu — the (+) button and the / menu are the
+						// host's, and this callback runs inside their boot
+						console.error("[dsh-git-badge] /gh contribution failed:", error);
+					}
+				});
+			}
+
 			// inject() re-evaluates when a seam's declaration appears, so boot
 			// order relative to the workspace browser does not matter. On an
 			// unpatched install the seam is never declared, so this callback never
@@ -895,7 +1313,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 };
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken, buildActions, actionText, ghSkillActions };
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -662,6 +662,93 @@ function operationMarker(gitDir) {
 	return null;
 }
 
+/**
+ * The one command a paused operation resumes with. A squash merge records no
+ * MERGE_HEAD (its conclusion is an ordinary commit), and bisect's next step is
+ * the user's judgement call (good/bad) — it gets a WHY but no command.
+ */
+const OPERATION_NEXT = {
+	merge: "git merge --continue",
+	squash: "git commit",
+	"cherry-pick": "git cherry-pick --continue",
+	revert: "git revert --continue",
+	rebase: "git rebase --continue",
+	sequencer: "git cherry-pick --continue",
+	bisect: void 0
+};
+
+/**
+ * The hover card's "next" row: the single highest-priority thing to do next,
+ * as a conservative command plus the reason it applies. Pure derivation over
+ * fields the status response already carries — no extra git invocations, so it
+ * rides the base response and a future surface gets it for free. Ranking (the
+ * first match wins):
+ *
+ *   1. a paused operation (conflicts included) — resuming it subsumes everything
+ *      else; unmerged files without a marker fall back to `git status`
+ *   2. behind — reconciling comes before publishing
+ *   3. no upstream on a dirty branch — publish it for the first time
+ *   4. ahead — publish
+ *   5. dirty — stage and commit (add -p for unstaged work; -A only when the
+ *      change is untracked-only, which add -p cannot see)
+ *   6. PR checks failing — watch them land
+ *
+ * Clean, synced, nothing failing → null: the row is omitted entirely, because
+ * "no suggestion" is also a suggestion. Commands are conservative on purpose —
+ * the card COPIES them into the user's terminal, it never runs them, but the
+ * register still avoids anything destructive.
+ *
+ * @returns {{ command: string|undefined, why: string } | null}
+ */
+function nextStep(info) {
+	if (info === void 0 || info === null || info.git !== true) return null;
+	const unmerged = info.unmergedFiles || 0;
+	const plural = (n) => (n === 1 ? "" : "s");
+	if (info.operation !== void 0 && info.operation !== null) {
+		const op = String(info.operation);
+		return {
+			command: OPERATION_NEXT[op],
+			why: unmerged > 0
+				? `${unmerged} unmerged file${plural(unmerged)} blocking the paused ${op}`
+				: `a ${op} is paused mid-operation`
+		};
+	}
+	if (unmerged > 0) {
+		return { command: "git status", why: `${unmerged} unmerged file${plural(unmerged)} to resolve` };
+	}
+	const ahead = info.ahead || 0;
+	const behind = info.behind || 0;
+	if (behind > 0) {
+		return { command: "git pull --ff-only", why: `${behind} behind ${info.upstream ?? "upstream"}` };
+	}
+	const staged = info.stagedFiles || 0;
+	const unstaged = info.unstagedFiles || 0;
+	const untracked = info.untrackedFiles || 0;
+	if (info.upstream === void 0 && staged + unstaged + untracked > 0) {
+		return { command: `git push -u origin ${info.branch}`, why: "no upstream configured" };
+	}
+	if (ahead > 0) {
+		return { command: "git push", why: `${ahead} ahead of ${info.upstream ?? "upstream"}` };
+	}
+	if (staged + unstaged + untracked > 0) {
+		const why = [
+			staged > 0 ? `${staged} staged` : null,
+			unstaged > 0 ? `${unstaged} unstaged` : null,
+			untracked > 0 ? `${untracked} untracked` : null
+		].filter(Boolean).join(", ");
+		const command = staged > 0
+			? "git commit"
+			: untracked > 0 && unstaged === 0
+				? "git add -A && git commit"
+				: "git add -p && git commit";
+		return { command, why: `work to commit: ${why}` };
+	}
+	if (info.pr !== void 0 && info.pr !== null && info.pr.number !== void 0 && info.pr.state === "failing") {
+		return { command: `gh pr checks ${info.pr.number} --watch`, why: `checks failing on #${info.pr.number}` };
+	}
+	return null;
+}
+
 /**
  * Git status for dir; { git: false } when dir is not a repository,
  * GIT_DEGRADED on transient git failure.
@@ -787,6 +874,8 @@ 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 (next !== null) info.next = next;
 	return info;
 }
 
@@ -1355,6 +1444,7 @@ export {
 	config,
 	OPERATION_MARKERS,
 	operationMarker,
+	nextStep,
 	outerGitDir,
 	parseStatusV2,
 	parseWorktreeList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -47,17 +47,19 @@
     "node": ">=20"
   },
   "files": [
-    "lib/index.js",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "cordis.patch.yml",
     "lib/client.js",
-    "seam/apply.js",
+    "lib/index.js",
+    "package.json",
     "seam/anchors.js",
+    "seam/apply.js",
     "seam/postinstall.js",
+    "seam/skill.js",
     "seam/store.js",
     "seam/stub-index.js",
-    "cordis.patch.yml",
-    "package.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "skill/gh/SKILL.md"
   ]
 }

package/seam/apply.js

@@ -55,6 +55,7 @@ import {
 	seamPresent,
 } from "./anchors.js";
 
+import { installSkill } from "./skill.js";
 import { dataDir, writeRestartMarker } from "./store.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -165,6 +166,11 @@ function writeText(path, text) {
 
 const VERDICT_EXIT_1 = new Set(["drift", "unreadable", "missing", "ours-corrupt"]);
 
+// keep the /gh skill in step with the package on every patcher run
+if (["apply", "revert", "status"].includes(process.argv[2])) {
+	console.log(`[dsh-git-badge] gh skill: ${installSkill()}`);
+}
+
 const verb = process.argv[2];
 if (!verb || !["apply", "revert", "status"].includes(verb)) {
 	console.error("usage: apply.js apply|revert|status");

package/seam/postinstall.js

@@ -26,6 +26,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyPatch, firstFailure, isOurs, seamPresent } from "./anchors.js";
+import { installSkill } from "./skill.js";
 import { dataDir, writeRestartMarker } from "./store.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -41,6 +42,9 @@ function dshClientPath() {
 }
 
 function main() {
+	// The skill does not depend on the DSH install — install it before any
+	// client-shaped early return, so a market install always gets /gh.
+	console.log(`[dsh-git-badge] gh skill: ${installSkill()} — /gh in the input's commands menu.`);
 	const client = dshClientPath();
 	if (client === null || !existsSync(client)) {
 		console.log(`[dsh-git-badge] DSH install not found; skipping seam setup. ${HINT}`);

package/seam/skill.js

@@ -0,0 +1,53 @@
+/**
+ * The gh skill installer — copies the packaged skill into the user's skills
+ * catalog so `/gh` exists in the input's commands menu.
+ *
+ * WHY A SKILL: the commands menu executes git through the AGENT, not through
+ * this plugin — the agent owns the approval/sandbox semantics for mutating
+ * commands. The skill is the knowledge; the `/gh` command contribution in the
+ * client half is only the state-aware menu entry that invokes it.
+ *
+ * GUARDRAILS — a skill must never break an install: every failure path returns
+ * a reason string instead of throwing, and a current target is a no-op (the
+ * byte comparison makes reinstalls and updates idempotent).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const SKILL_NAME = "gh";
+
+/** The user-level skills catalog — DSH_HOME honours the harness override. */
+export function skillsDir() {
+	return join(process.env.DSH_HOME || join(process.env.HOME || "", ".dsh"), "skills");
+}
+
+export function skillSource() {
+	return join(HERE, "..", "skill", "gh", "SKILL.md");
+}
+
+export function skillTarget() {
+	return join(skillsDir(), SKILL_NAME, "SKILL.md");
+}
+
+/**
+ * Install (or update) the gh skill. Never throws.
+ * @returns {"installed"|"current"|"no packaged skill"|string} what happened.
+ */
+export function installSkill() {
+	try {
+		const source = skillSource();
+		if (!existsSync(source)) return "no packaged skill";
+		const target = skillTarget();
+		mkdirSync(dirname(target), { recursive: true });
+		if (existsSync(target) && readFileSync(target, "utf8") === readFileSync(source, "utf8")) {
+			return "current";
+		}
+		copyFileSync(source, target);
+		return "installed";
+	} catch (error) {
+		return "skipped (" + String(error?.message ?? error) + ")";
+	}
+}

package/skill/gh/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: gh
+description: Git and GitHub operations for the current checkout, driven by an invocation argument — /gh push, /gh pr, /gh pull, /gh commit, /gh checks <n>, or bare /gh to do the single highest-priority next action.
+whenToUse: When the user picks a git action from the commands menu (/gh push, /gh pr, …) or asks to sync, publish, or open a pull request for the checkout they are working in.
+---
+
+# gh — git/GitHub actions for this checkout
+
+You are invoked as `/gh <sub>` (or bare `/gh`). The sub-command chooses the
+operation. Anything destructive requires explicit user confirmation before you
+run it, every command is reported with its output, and a failure is reported
+verbatim rather than retried blind.
+
+## First: establish state
+
+Run one status call and read it before acting (except for `checks`, which acts
+on its argument):
+
+```
+git --no-optional-locks status --porcelain=v2 --branch
+```
+
+Note branch, upstream, ahead/behind, and the dirty breakdown (staged /
+unstaged / untracked / unmerged), plus any in-progress operation marker
+(MERGE_HEAD, rebase-merge, …).
+
+## Sub-commands
+
+- **`/gh next`** (or bare `/gh`) — do the single highest-priority action, first
+  match wins: resume a paused operation (`git merge --continue`,
+  `git rebase --continue`, …; a squash merge concludes with `git commit`);
+  resolve unmerged files only WITH the user; `git pull --ff-only` when behind;
+  `git push -u origin <branch>` when there is no upstream; `git push` when
+  ahead; stage and commit when dirty (`git commit` if work is already staged,
+  `git add -p && git commit` for unstaged edits, `git add -A && git commit`
+  only for untracked-only changes, which `add -p` cannot see); `gh pr checks
+  <n> --watch` when CI fails. Clean and synced → say so and stop.
+
+- **`/gh push`** — `git push`. If there is no upstream, `git push -u origin
+  <branch>`. If the push is rejected as non-fast-forward, STOP and ask: offer
+  `--force-with-lease` as the option, never plain `--force`, and never without
+  an explicit yes.
+
+- **`/gh pr`** — create a pull request for the current branch: push first if
+  needed, then `gh pr create` with a title from the branch's commits and a body
+  summarising them. If a PR already exists, report its state (`gh pr view`)
+  instead of creating another.
+
+- **`/gh pull`** — `git pull --ff-only`. On failure, report the divergence and
+  ask; do not merge or rebase without the user choosing.
+
+- **`/gh commit`** — commit the current work: `git commit` when work is already
+  staged; otherwise `git add -p` interactively is not available to you, so
+  stage deliberately (`git add <paths>` named from the status output) and say
+  exactly what you staged before committing. Untracked-only changes: `git add
+  -A && git commit` after listing what -A will pick up. Write the message from
+  the diff, not a template.
+
+- **`/gh checks <n>`** — `gh pr checks <n>` and summarise: what fails, what is
+  pending, and the single most useful next step.
+
+## Hard rules
+
+- Never `git reset --hard`, `git clean`, `git checkout -- .`, `git push
+  --force` (plain), or any history rewrite without an explicit user yes.
+- `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.