dsh-git-badge 0.19.0 → 0.20.1

package/lib/index.js

@@ -69,7 +69,8 @@
 import { execFile } from "node:child_process";
 import { watch, existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, join, resolve } from "node:path";
-import { SESSION_CHECKOUT_TTL_MS, clearRestartMarker, readRestartMarker, readSessionCheckouts } from "../seam/store.js";
+import { SESSION_CHECKOUT_TTL_MS, readSessionCheckouts } from "../seam/store.js";
+import { installSkill } from "../seam/skill.js";
 
 const inject = ["webServer", "workspaceRegistry"];
 const name = "dsh-git-badge";
@@ -145,19 +146,14 @@ const config = {
 	 * timeout) is covered with no gh, no network and no forge.
 	 */
 	prRunner: null,
-	/**
-	 * Bound on the repository-wide open-PR read (`gh pr list`). Only one page is
-	 * read, so a repository with more open PRs than this simply has the excess
-	 * invisible to worktree selection; the checkout's own PR read is unaffected.
-	 */
-	prListLimit: 50,
 	/**
 	 * Worktree-aware status: "auto" lets a SESSION-targeted badge follow the one
-	 * linked worktree whose branch has an open PR, so a conversation doing its
-	 * work in a worktree reports that tree instead of the main checkout its
-	 * directory names; "off" always reports the session's own directory. A
-	 * workspace-targeted row never follows a worktree whatever this is set to — a
-	 * row surveys the checkout the registry owns. See effectiveTarget.
+	 * linked worktree the session registered for itself, so a conversation doing
+	 * its work in a worktree reports that tree instead of the main checkout its
+	 * directory names; the plugin never guesses a worktree from pull requests;
+	 * "off" always reports the session's own directory. A workspace-targeted row
+	 * never follows a worktree whatever this is set to — a row surveys the
+	 * checkout the registry owns. See effectiveTarget.
 	 */
 	worktreeStatus: "auto"
 };
@@ -255,6 +251,15 @@ function singleFlight(store, key, { ttlMs = 0, keepValue = false, serve }, run)
  */
 const defaultBranchState = new Map();
 
+/** The first existing of origin/main and origin/master, or null. */
+async function originBaseName(toplevel) {
+	for (const candidate of ["main", "master"]) {
+		const probe = await runGit(toplevel, ["rev-parse", "--verify", "--quiet", "refs/remotes/origin/" + candidate]);
+		if (probe.stdout !== null && probe.stdout.trim() !== "") return candidate;
+	}
+	return null;
+}
+
 /** The cached default branch, kicking a refresh when stale. Never throws. */
 function defaultBranchFor(toplevel, notify) {
 	return singleFlight(defaultBranchState, toplevel, {
@@ -274,10 +279,8 @@ function defaultBranchFor(toplevel, notify) {
 			// back, network-free, to the same base branch this module already
 			// probes for its ahead/behind row. A repository whose default branch is
 			// neither main nor master still answers undefined, exactly as before.
-			for (const candidate of ["main", "master"]) {
-				const probe = await runGit(toplevel, ["rev-parse", "--verify", "--quiet", "refs/remotes/origin/" + candidate]);
-				if (probe.stdout !== null && probe.stdout.trim() !== "") { name = candidate; break; }
-			}
+			const fallback = await originBaseName(toplevel);
+			if (fallback !== null) name = fallback;
 		}
 		const value = name === "" ? void 0 : name;
 		if (record.value !== value) notify?.();
@@ -285,9 +288,40 @@ function defaultBranchFor(toplevel, notify) {
 	});
 }
 
+/**
+ * toplevel+branch -> { ahead, behind } against the branch's BASE (origin/main,
+ * then origin/master). Cached and refreshed out of band, like the default branch.
+ *
+ * The branch's relation to its base used to be detail-only (`detail=1`, the chip's
+ * hover card). The IDLE icon's colour needs it on EVERY response: green when no
+ * commit is ahead of the base, amber when some are. Reading it in only one path
+ * made the chip and the row say green while the card said amber — the same
+ * checkout, two answers. A rev-list per refresh is too expensive on the hot path,
+ * so the first read may answer without the relation and the next one carries it.
+ */
+const baseRelationState = new Map();
+
+/** The cached branch-vs-base relation, kicking a refresh when stale. Never throws. */
+function baseRelationFor(toplevel, branch, notify) {
+	return singleFlight(baseRelationState, toplevel + "\u0000" + branch, {
+		ttlMs: config.defaultBranchTtlMs,
+		keepValue: true,
+		serve: (state) => state.value
+	}, async (record) => {
+		const candidate = await originBaseName(toplevel);
+		if (candidate === null) return void 0;
+		const base = "origin/" + candidate;
+		const out = await runGit(toplevel, ["rev-list", "--count", "--left-right", base + "...HEAD"]);
+		const [behind, ahead] = (out.stdout ?? "").trim().split("\t").map((v) => Number.parseInt(v, 10));
+		if (!Number.isFinite(ahead) || !Number.isFinite(behind)) return void 0;
+		const value = { ahead, behind, base: candidate };
+		if (record.value?.ahead !== value.ahead || record.value?.behind !== value.behind) notify?.();
+		return value;
+	});
+}
+
 /** lastFetchAt per toplevel; in-flight promise per toplevel collapses races. */
 const fetchState = new Map();
-
 /**
  * Refresh the remote-tracking refs for toplevel, bounded by TTL. Resolves
  * true only when a fetch actually ran and succeeded; every failure mode
@@ -344,10 +378,6 @@ async function maybeFetch(toplevel) {
 /** 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
@@ -372,13 +402,11 @@ async function originIsGitHub(toplevel) {
  * 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);
@@ -386,7 +414,7 @@ function summarizeChecks(checks) {
 		// unfinished: a CheckRun that has not completed, or a StatusContext PENDING
 		if (state === "PENDING" || (status !== "" && status !== "COMPLETED")) sawPending = true;
 	}
-	if (!sawAny) return "none";
+	if (checks.length === 0) return "none";
 	return sawPending ? "pending" : "passing";
 }
 
@@ -409,9 +437,9 @@ function summarizePr(json) {
 	// GitHub's OWN merge verdict (CLEAN / BLOCKED / BEHIND / DIRTY / DRAFT /
 	// UNSTABLE / HAS_HOOKS / UNKNOWN), passed through rather than re-derived here:
 	// whether a PR is mergeable depends on branch protection and required reviews,
-	// which is the forge's business and not this plugin's to interpret. `gh pr list`
-	// does not ask for it, so a worktree-candidate entry simply has no `mergeState`
-	// — absence is the contract, as everywhere else in this half.
+	// which is the forge's business and not this plugin's to interpret. It is
+	// omitted when `gh` did not report it — absence is the contract, as
+	// everywhere else in this half.
 	if (typeof json.mergeStateStatus === "string" && json.mergeStateStatus !== "") pr.mergeState = json.mergeStateStatus.toUpperCase();
 	// 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
@@ -437,7 +465,7 @@ 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,mergeStateStatus"], {
+	const out = await (config.prRunner ?? runCli)("gh", ["pr", "view", branch, "--json", "number,state,isDraft,reviewDecision,statusCheckRollup,url,mergeStateStatus"], {
 		cwd: toplevel,
 		timeout: config.prTimeoutMs,
 		// GH_PROMPT_DISABLED: an auth prompt must never hang the refresh (the gh
@@ -456,13 +484,6 @@ async function readPrStatus(toplevel, branch) {
 	return summarizePr(json);
 }
 
-
-/** Order-insensitive identity for an open-PR set, so "did it change?" is exact. */
-function prListKey(byBranch) {
-	if (byBranch === void 0) return "";
-	return JSON.stringify([...byBranch].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
-}
-
 /**
  * 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
@@ -546,22 +567,20 @@ function parseStatusV2(out) {
 			if (Number.isFinite(a)) ahead = a;
 			if (Number.isFinite(b)) behind = b;
 		} else if (line.startsWith("1 ") || line.startsWith("2 ")) {
-			// XY columns: X = index (staged), Y = worktree (unstaged)
+			// XY columns: X = index (staged), Y = worktree (unstaged). The path is
+			// the LAST field in both record shapes (space-separated, and the path
+			// itself may contain spaces), so it is computed once per record and
+			// shared by both columns — collected untruncated and capped by the
+			// caller, exactly like the untracked names.
+			const path = line.startsWith("2 ")
+				? line.split("\t").pop().trim()
+				: line.split(" ").slice(8).join(" ").trim();
 			if (line[2] !== ".") {
 				staged += 1;
-				const path = line.startsWith("2 ")
-					? line.split("\t").pop().trim()
-					: line.split(" ").slice(8).join(" ").trim();
 				if (path !== "") stagedNames.push(path);
 			}
 			if (line[3] !== ".") {
 				unstaged += 1;
-				// the path is the LAST field in both records (space-separated, and
-				// the path itself may contain spaces) — collected untruncated and
-				// capped by the caller, exactly like the untracked names
-				const path = line.startsWith("2 ")
-					? line.split("\t").pop().trim()
-					: line.split(" ").slice(8).join(" ").trim();
 				if (path !== "") unstagedNames.push(path);
 			}
 		} else if (line.startsWith("u ")) unmerged += 1;
@@ -577,6 +596,14 @@ function parseStatusV2(out) {
 	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked, untrackedNames, unstagedNames, stagedNames };
 }
 
+/** Parse a plain (unsigned) `log --format=%h%x09%s%x09%cr` body: hash, subject, relative time. */
+function parseCommitLines(stdout) {
+	return 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);
+}
+
 /**
  * Parse `git worktree list --porcelain`. Blocks of `key value` lines separated by
  * a blank line: `worktree <path>`, `HEAD <sha>`, `branch refs/heads/<name>` (the
@@ -702,13 +729,18 @@ const OPERATION_NEXT = {
  * below (first match wins) is the default, and a user can override it by
  * naming categories in `~/.dsh/git-badge-next.json`:
  *
- *   { "order": ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"] }
+ *   { "order": ["operation", "unmerged", "conflict", "review", "sync", "publish", "merge", "commit", "checks"] }
  *
  * Any subset in any order; categories not listed rank after the listed ones in
  * default order, unknown names are ignored. Typically edited for you by the
  * agent via `/gh order`.
+ *
+ * Migration note: `conflict` and `review` were added after an existing user's
+ * stored order was written. `normalizeOrder` appends the categories they did
+ * not list, so an old seven-category order ranks the two last until the user
+ * reorders them in Settings. Nothing re-ranks silently.
  */
-const DEFAULT_NEXT_ORDER = ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"];
+const DEFAULT_NEXT_ORDER = ["operation", "unmerged", "conflict", "review", "sync", "publish", "merge", "commit", "checks"];
 
 /** Normalise any order list: known categories first, then the rest in default order. */
 function normalizeOrder(order) {
@@ -763,11 +795,6 @@ function seedOrder() {
 	currentOrder = legacyOrderFile();
 }
 
-/** The ranking order every status read uses. */
-function nextOrder() {
-	return currentOrder;
-}
-
 /**
  * The hover card's "action" row and the (+) menu's picker: every sub-action the
  * checkout justifies, each as a `gh`-skill invocation ({ args, why, what } —
@@ -776,7 +803,7 @@ function nextOrder() {
  * invocations, so it rides the base response.
  *
  * Ranking: rule candidates are collected with a category, then sorted by the
- * configured order (nextOrder) — NOT first-match — so a configuration can, for
+ * configured order (currentOrder) — NOT first-match — so a configuration can, for
  * example, rank "commit" above "sync" without touching code. Ties keep
  * collection order.
  *
@@ -791,7 +818,7 @@ function nextOrder() {
  * Clean, synced, nothing failing → null: the row is omitted entirely, because
  * "no suggestion" is also a suggestion.
  *
- * @returns {{ args: string, command: string|undefined, why: string, what: string } | null}
+ * @returns {{ args: string|null, cat: string, command: string|undefined, why: string, what: string, token: string|null, severity: string|null } | null}
  */
 function nextStepRules(info) {
 	if (info === void 0 || info === null || info.git !== true) return null;
@@ -804,7 +831,13 @@ function nextStepRules(info) {
 	const untracked = info.untrackedFiles || 0;
 	const dirty = staged + unstaged + untracked;
 	const rules = [];
-	const add = (cat, args, why, what, command) => rules.push({ cat, args, why, what, command });
+	// `args` is the `/gh` invocation, or null for a ROW-ONLY rule the `gh` skill
+	// has no verb for (the picker must not offer a verb that does not exist).
+	// `token` is the row's one-word imperative for the rule, or null.
+	// `severity` is the ONE colour role every surface paints the icon with:
+	// error | warn | success | business. The client holds no token-to-colour map,
+	// so the chip and the row cannot disagree about how loud a state is.
+	const add = (cat, args, why, what, command, token, severity) => rules.push({ cat, args, why, what, command, token, severity });
 
 	if (info.operation !== void 0 && info.operation !== null) {
 		const op = String(info.operation);
@@ -813,25 +846,57 @@ function nextStepRules(info) {
 				? `${unmerged} unmerged file${plural(unmerged)} blocking the paused ${op}`
 				: `a ${op} is paused mid-operation`,
 			`resume the paused ${op}`,
-			OPERATION_NEXT[op]);
+			OPERATION_NEXT[op],
+			"resume",
+			"error");
 	}
 	if (unmerged > 0) {
-		add("unmerged", "next", `${unmerged} unmerged file${plural(unmerged)} to resolve`, "resolve the unmerged files (with you)", "git status");
+		add("unmerged", "next", `${unmerged} unmerged file${plural(unmerged)} to resolve`, "resolve the unmerged files (with you)", "git status", "resolve", "error");
 	}
 	if (behind > 0 && ahead > 0) {
-		add("sync", "sync", `${ahead} ahead, ${behind} behind — diverged`, "rebase your commits onto upstream and push (asks before any force)");
+		add("sync", "sync", `${ahead} ahead, ${behind} behind — diverged`, "rebase your commits onto upstream and push (asks before any force)", void 0, "sync", "business");
 	} else if (behind > 0) {
-		add("sync", "pull", `${behind} behind ${info.upstream ?? "upstream"}`, "update this branch from upstream", "git pull --ff-only");
+		add("sync", "pull", `${behind} behind ${info.upstream ?? "upstream"}`, "update this branch from upstream", "git pull --ff-only", "pull", "business");
 	}
+	// The upstream is `<remote>/<branch>`. A branch created from `origin/main`
+	// tracks origin/main, and a bare `git push` is refused there under the default
+	// `push.default=simple`, because the upstream branch name does not match the
+	// local branch name. Treat that as "publish under its own name", which pushes
+	// AND repairs the tracking in one step.
+	const upstreamSlash = typeof info.upstream === "string" ? info.upstream.indexOf("/") : -1;
+	const upstreamRemote = upstreamSlash > 0 ? info.upstream.slice(0, upstreamSlash) : "origin";
+	const upstreamBranch = upstreamSlash > 0 ? info.upstream.slice(upstreamSlash + 1) : void 0;
+	const upstreamNamesOtherBranch = typeof info.branch === "string" && info.branch !== ""
+		&& upstreamBranch !== void 0 && upstreamBranch !== info.branch;
 	if (info.upstream === void 0 && dirty > 0) {
-		add("publish", "push", "no upstream configured", `publish ${info.branch} for the first time`, `git push -u origin ${info.branch}`);
+		add("publish", "push", "no upstream configured", `publish ${info.branch} for the first time`, `git push -u origin ${info.branch}`, "push", "business");
+	} else if (ahead > 0 && upstreamNamesOtherBranch) {
+		add("publish", "push", `${ahead} ahead of ${info.upstream} (tracks a different branch)`, `publish ${info.branch} under its own name and set its upstream`, `git push -u ${upstreamRemote} ${info.branch}`, "push", "business");
 	} else if (ahead > 0) {
-		add("publish", "push", `${ahead} ahead of ${info.upstream ?? "upstream"}`, "push local commits to the remote", "git push");
+		add("publish", "push", `${ahead} ahead of ${info.upstream ?? "upstream"}`, "push local commits to the remote", "git push", "push", "business");
 	}
 	const pr = info.pr === void 0 || info.pr === null ? void 0 : info.pr;
-	if (pr !== void 0 && pr.number !== void 0 && pr.open !== false
-		&& (pr.mergeState === "CLEAN" || (pr.state === "passing" && pr.review === "APPROVED"))) {
-		add("merge", `merge ${pr.number}`, `pull request ${pr.number} is ready to merge`, `merge pull request ${pr.number} (squash)`);
+	const hasPr = pr !== void 0 && pr.number !== void 0;
+	const openPr = hasPr && pr.open !== false;
+	// PR states no `/gh` verb covers: ROW-ONLY rules. They carry the row's token
+	// and `args: null`, so they triage on the row without the picker offering a
+	// verb the skill does not have. They ride the same ranking as everything
+	// else, so a row-only rule can sit above the first picker-eligible one.
+	if (openPr) {
+		if (pr.mergeState === "DIRTY") {
+			add("conflict", null, `pull request ${pr.number} conflicts with its base`, `resolve the conflict on pull request ${pr.number}`, void 0, "resolve", "error");
+		}
+		if (pr.review === "CHANGES_REQUESTED") {
+			add("review", null, `changes requested on pull request ${pr.number}`, `address the review on pull request ${pr.number}`, void 0, "review", "warn");
+		} else if (pr.review === "REVIEW_REQUIRED") {
+			add("review", null, `pull request ${pr.number} needs a review`, `get pull request ${pr.number} reviewed`, void 0, "review", "warn");
+		}
+		if (pr.mergeState === "BEHIND") {
+			add("sync", null, `pull request ${pr.number} is behind its base`, `update pull request ${pr.number} from its base`, void 0, "update", "business");
+		}
+	}
+	if (openPr && (pr.mergeState === "CLEAN" || (pr.state === "passing" && pr.review === "APPROVED"))) {
+		add("merge", `merge ${pr.number}`, `pull request ${pr.number} is ready to merge`, `merge pull request ${pr.number} (squash)`, void 0, "merge", "success");
 	}
 	if (dirty > 0) {
 		const parts = [
@@ -844,10 +909,10 @@ function nextStepRules(info) {
 			: untracked > 0 && unstaged === 0
 				? "git add -A && git commit"
 				: "git add -p && git commit";
-		add("commit", "commit", `work to commit: ${parts}`, staged > 0 ? "commit the staged changes" : "stage and commit the working changes", command);
+		add("commit", "commit", `work to commit: ${parts}`, staged > 0 ? "commit the staged changes" : "stage and commit the working changes", command, "commit", "business");
 	}
-	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 (hasPr && 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`, "fix CI", "error");
 	}
 
 	// STANDING options: never ranked, never the primary suggestion — they are
@@ -856,7 +921,7 @@ function nextStepRules(info) {
 	// 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) {
+	if (hasPr) {
 		standing.push({
 			args: `pr view ${pr.number}`,
 			why: `open pull request #${pr.number}`,
@@ -874,7 +939,7 @@ function nextStepRules(info) {
 		});
 	}
 
-	const order = nextOrder();
+	const order = currentOrder;
 	const rank = (cat) => {
 		const at = order.indexOf(cat);
 		return at === -1 ? order.length : at;
@@ -892,18 +957,31 @@ function nextStepRules(info) {
  * 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.
+ * Exactly one entry can be `primary` (the top RANKED rule that has a `/gh`
+ * verb) 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.
+ *
+ * `rowToken` is the row's own verdict: the first ranked rule with a non-null
+ * `token`. It may name a ROW-ONLY rule (a PR conflict, a requested review) that
+ * never enters `actions`, so the row triages while the chip and picker offer
+ * only real actions. `rowWhy` is that same rule's reason, so a surface with no
+ * room for the word (the leading glyph) can say WHY on hover. `rowSeverity` is
+ * the same rule's colour role, so every surface paints the icon the same way.
+ * With NO rule at all the three become the idle verdict: the token `in sync`,
+ * a reason, and a severity that is `success` when no commit is ahead of the base
+ * and `warn` when some are. Only a non-repository returns null.
  *
- * @returns {{ actions: Array<{args, why, what, command?, danger?, primary?}>, next: object|null }}
+ * @returns {{ actions: Array<{args, why, what, command?, danger?, primary?}>, next: object|null, rowToken: string|null, rowWhy: string|null, rowSeverity: string|null }}
  */
 function nextActions(info) {
 	const built = nextStepRules(info);
-	if (built === null) return { actions: [], next: null };
+	if (built === null) return { actions: [], next: null, rowToken: null, rowWhy: null, rowSeverity: null };
 	const { ranked, standing } = built;
+	// Row-only rules carry `args: null` and are dropped here: the picker must
+	// never offer a `/gh` verb the skill does not have.
+	const offerable = ranked.filter((rule) => typeof rule.args === "string");
 	const actions = [
-		...ranked.map((rule, index) => ({
+		...offerable.map((rule, index) => ({
 			args: rule.args,
 			why: rule.why,
 			what: rule.what,
@@ -913,7 +991,86 @@ function nextActions(info) {
 		...standing
 	];
 	const primary = actions.find((action) => action.primary === true) ?? null;
-	return { actions, next: primary };
+	// The winning row rule supplies the token, its reason AND its severity, so the
+	// three can never describe different rules.
+	const rowRule = ranked.find((rule) => rule.token !== null && rule.token !== void 0) ?? null;
+	// NO rule fired: the checkout is clean and nothing local needs doing. The WORD
+	// says only what is known — "in sync" — and the COLOUR says whether work is
+	// still unmerged. `mainAhead` counts commits on this branch that its base does
+	// not have, so an amber disc means "clean, pushed, and not merged"; green means
+	// the branch is the default branch, or its work is already in the base. This is
+	// NOT a ranked rule and NOT a picker entry: no `/gh` verb covers it. A
+	// non-repository still returns null (see above).
+	const notMerged = info.mainAhead || 0;
+	const idle = notMerged > 0
+		? { why: notMerged + " commit" + (notMerged === 1 ? "" : "s") + " not merged", severity: "warn" }
+		: { why: "clean and matching the remote", severity: "success" };
+	return {
+		actions,
+		next: primary,
+		rowToken: rowRule?.token ?? "in sync",
+		rowWhy: rowRule?.why ?? idle.why,
+		rowSeverity: rowRule?.severity ?? idle.severity
+	};
+}
+
+/**
+ * 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 refresh pays for it.
+ * Posture: RELATIVE names only (git's own output, never absolute — AGENTS.md
+ * rule 7 is relaxed by an inch, not a mile), shortened to the last two path
+ * segments, capped at 20 with the total carried separately so the client can
+ * say "… and k more" honestly. Staged and unstaged names are TRACKED files: the
+ * collapsed untracked retry never affects them, so they ride regardless of
+ * untrackedMode.
+ */
+function attachDetail(info, parsed, untrackedMode) {
+	const capped = (names) => names.slice(0, 20).map(shortenPath);
+	if (untrackedMode === "all" && parsed.untrackedNames.length > 0) {
+		info.untrackedNames = capped(parsed.untrackedNames);
+		info.untrackedNamesTotal = parsed.untrackedNames.length;
+	}
+	if (parsed.unstagedNames.length > 0) {
+		info.unstagedNames = capped(parsed.unstagedNames);
+		info.unstagedNamesTotal = parsed.unstagedNames.length;
+	}
+	if (parsed.stagedNames.length > 0) {
+		info.stagedNames = capped(parsed.stagedNames);
+		info.stagedNamesTotal = parsed.stagedNames.length;
+	}
+}
+
+/**
+ * The signed commit list: mixed newest-first from base...HEAD, each entry signed
+ * "+" (only on this branch - the PR's content) or "−" (only on main - what a
+ * rebase/merge brings in), git's own left-right verdict mapped onto the diff
+ * convention. Capped at 10 with the total from the same base so "... and k more"
+ * counts both sides. Called only when a base ref resolved; without one the
+ * caller serves the plain HEAD log instead.
+ */
+async function attachBranchCommits(info, toplevel, baseRef, logHead) {
+	if (baseRef !== null) {
+		const signedOut = await runGit(toplevel, ["log", "--left-right", "-10", "--format=%m%x09%h%x09%s%x09%cr", baseRef + "...HEAD"]);
+		if (signedOut.stdout !== null && signedOut.stdout.trim() !== "") {
+			info.branchCommits = signedOut.stdout.trim().split("\n").map((line) => {
+				const [marker, hash, subject, when] = line.split("\t");
+				return {
+					sign: marker === ">" ? "+" : marker === "<" ? "−" : void 0,
+					hash,
+					subject: subject ?? "",
+					when: when ?? ""
+				};
+			}).filter((c) => c.hash !== void 0);
+			const totalOut = await runGit(toplevel, ["rev-list", "--count", baseRef + "...HEAD"]);
+			const total = Number.parseInt((totalOut.stdout ?? "").trim(), 10);
+			if (Number.isFinite(total)) info.branchCommitsTotal = total;
+		}
+	} else {
+		// already fetched in the batch above — no second invocation
+		if (logHead.stdout !== null && logHead.stdout.trim() !== "") {
+			info.branchCommits = parseCommitLines(logHead.stdout);
+		}
+	}
 }
 
 /**
@@ -1022,31 +1179,24 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 	// 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;
+	// The branch-vs-base relation rides EVERY response, because the IDLE icon's
+	// COLOUR depends on it: green when no commit is ahead of the base, amber when
+	// some are. It used to be detail-only, so the chip and the row said green while
+	// the hover card said amber. Cached like the default branch, so no refresh pays
+	// for a rev-list on the hot path; the first read may answer without it.
+	const relation = baseRelationFor(toplevel, parsed.branch, notifyChange);
+	if (relation !== void 0) {
+		info.mainBranch = relation.base;
+		if (relation.ahead > 0 || relation.behind > 0) {
+			info.mainAhead = relation.ahead;
+			info.mainBehind = relation.behind;
+		}
+	}
 	// 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
-		// refresh pays for it. Posture: RELATIVE names only (git's own output,
-		// never absolute — AGENTS.md rule 7 is relaxed by an inch, not a mile),
-		// shortened to the last two path segments, capped at 20 with the total
-		// carried separately so the client can say "… and k more" honestly.
-		// Staged and unstaged names are TRACKED files: the collapsed untracked
-		// retry never affects them, so they ride regardless of untrackedMode.
-		const capped = (names) => names.slice(0, 20).map(shortenPath);
-		if (untrackedMode === "all" && parsed.untrackedNames.length > 0) {
-			info.untrackedNames = capped(parsed.untrackedNames);
-			info.untrackedNamesTotal = parsed.untrackedNames.length;
-		}
-		if (parsed.unstagedNames.length > 0) {
-			info.unstagedNames = capped(parsed.unstagedNames);
-			info.unstagedNamesTotal = parsed.unstagedNames.length;
-		}
-		if (parsed.stagedNames.length > 0) {
-			info.stagedNames = capped(parsed.stagedNames);
-			info.stagedNamesTotal = parsed.stagedNames.length;
-		}
+		attachDetail(info, parsed, untrackedMode);
 		// The signed commit list and the counts-vs-main row: ahead/behind against origin/main (then
 		// origin/master) is the merge-state line — "3 ahead, 0 behind" reads as
 		// "this is the PR's content"; "0 ahead, 5 behind" as "stale, rebase
@@ -1086,6 +1236,7 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 			}
 		}
 		if (baseRef !== null) {
+			info.mainBranch = baseRef.replace(/^origin\//u, "");
 			const lrOut = await runGit(toplevel, ["rev-list", "--count", "--left-right", baseRef + "...HEAD"]);
 			const [mBehind, mAhead] = (lrOut.stdout ?? "").trim().split("\t").map((v) => Number.parseInt(v, 10));
 			if (Number.isFinite(mBehind) && Number.isFinite(mAhead) && (mBehind > 0 || mAhead > 0)) {
@@ -1093,37 +1244,7 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 				info.mainBehind = mBehind;
 			}
 		}
-		if (baseRef !== null) {
-			// The signed commit list: mixed newest-first from base...HEAD, each
-			// entry signed "+" (only on this branch - the PR's content) or "−"
-			// (only on main - what a rebase/merge brings in), git's own left-right
-			// verdict mapped onto the diff convention. Capped at 10 with the total
-			// from the same base so "... and k more" counts both sides. Without a
-			// default branch the list degrades to the plain last 10 on HEAD.
-			const signedOut = await runGit(toplevel, ["log", "--left-right", "-10", "--format=%m%x09%h%x09%s%x09%cr", baseRef + "...HEAD"]);
-			if (signedOut.stdout !== null && signedOut.stdout.trim() !== "") {
-				info.branchCommits = signedOut.stdout.trim().split("\n").map((line) => {
-					const [marker, hash, subject, when] = line.split("\t");
-					return {
-						sign: marker === ">" ? "+" : marker === "<" ? "−" : void 0,
-						hash,
-						subject: subject ?? "",
-						when: when ?? ""
-					};
-				}).filter((c) => c.hash !== void 0);
-				const totalOut = await runGit(toplevel, ["rev-list", "--count", baseRef + "...HEAD"]);
-				const total = Number.parseInt((totalOut.stdout ?? "").trim(), 10);
-				if (Number.isFinite(total)) info.branchCommitsTotal = total;
-			}
-		} else {
-			// already fetched in the batch above — no second invocation
-			if (logHead.stdout !== null && logHead.stdout.trim() !== "") {
-				info.branchCommits = logHead.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);
-			}
-		}
+		await attachBranchCommits(info, toplevel, baseRef, logHead);
 		if (stashOut.stdout !== null) {
 			const count = stashOut.stdout.split("\n").filter((l) => l.trim() !== "").length;
 			if (count > 0) info.stashCount = count;
@@ -1138,27 +1259,15 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
 		if (pr !== void 0) info.pr = pr;
 	}
-	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);
+	// The ranked suggestion AND the row's token ride EVERY response (both are
+	// pure derivation, and the sidebar row now reads the node half's token
+	// instead of re-deriving it); 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, rowToken, rowWhy, rowSeverity } = nextActions(info);
 	if (next !== null) info.next = next;
+	if (rowToken !== null) info.rowToken = rowToken;
+	if (rowWhy !== null) info.rowTokenWhy = rowWhy;
+	if (rowSeverity !== null) info.rowSeverity = rowSeverity;
 	if (wantPr && actions.length > 0) info.actions = actions;
 	return info;
 }
@@ -1237,7 +1346,7 @@ function closeWatchers(record) {
 		}
 	}
 	record.watcher = null;
-	if ("extra" in record) record.extra = null;
+	record.extra = null;
 }
 
 function unwatchWorkspace(key) {
@@ -1456,12 +1565,16 @@ function selectWorktreeWatch(ownerPath, workspaceId, chosenPath) {
 	selectedWorktrees.set(ownerPath, { worktreePath: chosenPath, workspaceId, owned });
 }
 
+/** The registry entities whose public surface carries a string `path`. */
+function listEntities(ctx) {
+	return ctx.workspaceRegistry.list().filter((entity) => typeof entity?.path === "string");
+}
+
 /** Reconcile the watcher set with the current workspace registry. */
 function syncWatchers(ctx) {
 	const wanted = new Set();
-	for (const entity of ctx.workspaceRegistry.list()) {
+	for (const entity of listEntities(ctx)) {
 		// `path` and `id` are the entity's public surface; its `record` is private
-		if (typeof entity?.path !== "string") continue;
 		wanted.add(entity.path);
 		watchWorkspace(entity.path, entity.path, entity.id === void 0 ? void 0 : String(entity.id));
 	}
@@ -1503,10 +1616,7 @@ async function resolveWorkspace(ctx, params) {
 	if (workspaceId === "" && sessionId === "") {
 		return { status: 400, error: { code: "target-required", message: "pass workspace=<id> or session=<id>" } };
 	}
-	const entities = [];
-	for (const entity of ctx.workspaceRegistry.list()) {
-		if (typeof entity?.path === "string") entities.push(entity);
-	}
+	const entities = listEntities(ctx);
 	if (workspaceId !== "") {
 		const entity = entities.find((candidate) => String(candidate.id) === workspaceId);
 		if (entity === void 0) {
@@ -1547,9 +1657,7 @@ async function resolveWorkspace(ctx, params) {
  */
 function sessionCheckouts() {
 	// The store owns the file's shape; the test seam only redirects the path.
-	return config.sessionCheckoutsFile === null
-		? readSessionCheckouts()
-		: readSessionCheckouts(config.sessionCheckoutsFile);
+	return readSessionCheckouts(config.sessionCheckoutsFile ?? undefined);
 }
 
 async function registeredCheckout(target, sessionId) {
@@ -1601,6 +1709,11 @@ async function effectiveTarget(target, sessionId) {
 
 /** Host plugin body — register the status route and the SSE change feed. */
 function apply(ctx) {
+	// The /gh skill must exist in the user's skills catalog for the commands
+	// menu to find it. Installing it here (not only from a CLI run) means a
+	// market install gets /gh on the next boot. installSkill() never throws: it
+	// returns a reason string, so a read-only home degrades to a console line.
+	console.log(`[dsh-git-badge] gh skill: ${installSkill()}`);
 	// The ranking order lives in this plugin's own settings namespace: declared
 	// with a schema so the host validates it, stored in the user's settings
 	// document, and observed live — a change applies to the next status read
@@ -1635,11 +1748,6 @@ function apply(ctx) {
 			console.error("[dsh-git-badge] settings namespace unavailable, using the legacy order file:", error);
 		}
 	}
-	// A fresh boot composed the files on disk into the new bundles — any
-	// restart-pending marker was written by an install/apply against the PREVIOUS
-	// boot and its change is now live. Clearing here is what makes the marker
-	// self-expiring: it survives exactly until the restart it asks for happens.
-	clearRestartMarker();
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/git-badge",
@@ -1652,7 +1760,6 @@ function apply(ctx) {
 					res.end(JSON.stringify({ git: false, error: target.error }));
 					return;
 				}
-				const pending = readRestartMarker();
 				const detail = url.searchParams.get("detail") === "1";
 				const pr = url.searchParams.get("pr") === "1";
 				// WHO asked decides whether a linked worktree may stand in for the
@@ -1702,12 +1809,6 @@ function apply(ctx) {
 				// tell whether an event belongs to it — without this the input chip
 				// only ever refreshed on remount or the 60s poll.
 				res.writeHead(200, { "content-type": "application/json" });
-				if (pending !== null) {
-					// dshmarket cannot see postinstall/apply host-file changes; this
-					// flag is how the running UI learns a restart is pending and
-					// offers its own Restart button (dshmarket v1 restart endpoint).
-					body.seamRestartPending = { by: pending.by, at: pending.at };
-				}
 				res.end(JSON.stringify(body));
 			} catch (error) {
 				res.writeHead(400, { "content-type": "application/json" });
@@ -1780,27 +1881,22 @@ export { apply, inject, name };
 // what lets a node-half change be verified without a restart.
 export {
 	config,
-	OPERATION_MARKERS,
-	operationMarker,
 	nextActions,
+	normalizeOrder,
 	seedOrder,
 	outerGitDir,
 	parseStatusV2,
 	parseWorktreeList,
 	readWorktrees,
-	worktreesFor,
 	runCli,
 	runGit,
 	gitStatus,
-	gitStatusUncached,
-	resolveWorkspace,
 	effectiveTarget,
 	readPrStatus,
 	summarizePr,
 	summarizeChecks,
 	prStatusFor,
 	prState,
-	selectWorktreeWatch,
 	selectedWorktrees,
 	statusInFlight,
 	watchWorkspace,