dsh-git-badge 0.14.1 → 0.16.0

package/lib/index.js

@@ -69,7 +69,7 @@
 import { execFile } from "node:child_process";
 import { watch, existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, join, resolve } from "node:path";
-import { clearRestartMarker, readRestartMarker } from "../seam/store.js";
+import { SESSION_CHECKOUT_TTL_MS, clearRestartMarker, readRestartMarker, readSessionCheckouts } from "../seam/store.js";
 
 const inject = ["webServer", "workspaceRegistry"];
 const name = "dsh-git-badge";
@@ -82,6 +82,13 @@ const name = "dsh-git-badge";
  * single documented seam.
  */
 const config = {
+	/**
+	 * Test seam: the session-checkout registrations file. Null (the default)
+	 * resolves it under the plugin's data dir (SEAM_DATA_DIR-aware store.js).
+	 */
+	sessionCheckoutsFile: null,
+	/** Test seam: resolves the schema lib the settings namespace is built from. */
+	settingsSchemaLoader: async () => (await import("@deepseek-ai/schemastery")).default,
 	/** budget for every git invocation; an expired call is killed */
 	gitTimeoutMs: 3000,
 	/** network fetch budget; worst-case route latency, paid once per TTL */
@@ -380,43 +387,6 @@ async function readPrStatus(toplevel, branch) {
 	return summarizePr(json);
 }
 
-/** toplevel -> { lastAttemptAt, inFlight, value: Map<branch, pr> }. */
-const prListState = new Map();
-
-/**
- * Every OPEN pull request in `toplevel`'s repository, keyed by its head branch.
- * ONE `gh pr list` answers the whole repository, which is what makes worktree
- * selection affordable: N worktrees cost one forge call, not N.
- *
- * Degrades exactly like readPrStatus, and for the same reason: a non-array body,
- * unparseable output, a logged-out `gh`, a non-GitHub `origin` and a timeout all
- * resolve an empty map. "No PRs" and "no forge" are the same answer here — both
- * mean no worktree can be shown to be the one the session is working in.
- */
-async function readOpenPrs(toplevel) {
-	if (!(await originIsGitHub(toplevel))) return new Map();
-	const out = await runPrCli("gh", ["pr", "list", "--state", "open", "--limit", String(config.prListLimit), "--json", "number,headRefName,state,isDraft,reviewDecision,statusCheckRollup,url"], {
-		cwd: toplevel,
-		timeout: config.prTimeoutMs,
-		env: { GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1" }
-	});
-	if (out.stdout === null) return new Map();
-	let json;
-	try {
-		json = JSON.parse(out.stdout);
-	} catch {
-		return new Map();
-	}
-	if (!Array.isArray(json)) return new Map();
-	const byBranch = new Map();
-	for (const row of json) {
-		const branch = row?.headRefName;
-		if (typeof branch !== "string" || branch === "") continue;
-		const pr = summarizePr(row);
-		if (pr !== void 0) byBranch.set(branch, pr);
-	}
-	return byBranch;
-}
 
 /** Order-insensitive identity for an open-PR set, so "did it change?" is exact. */
 function prListKey(byBranch) {
@@ -424,63 +394,6 @@ function prListKey(byBranch) {
 	return JSON.stringify([...byBranch].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
 }
 
-/**
- * Open PRs for toplevel: the value to serve NOW (possibly undefined), spawning an
- * out-of-band refresh when the TTL has lapsed — the same shape and the same
- * reasoning as prStatusFor, because the forge is never route latency.
- *
- * `notify` fires only when the set CHANGES: a changed set can change which
- * worktree a session badge follows, so the client has to be told to refetch
- * rather than waiting for its 60s safety-net poll.
- */
-function openPrsFor(toplevel, notify) {
-	if (config.prStatus === "off") return void 0;
-	const now = Date.now();
-	const state = prListState.get(toplevel);
-	if (state !== void 0) {
-		// Fresh, or a refresh is already running: serve what we have either way.
-		if (now - state.lastAttemptAt < config.prTtlMs || state.inFlight !== null) return state.value;
-	}
-	const record = { lastAttemptAt: now, inFlight: null, value: state?.value };
-	const inFlight = (async () => {
-		const value = await readOpenPrs(toplevel).catch(() => void 0);
-		if (value !== void 0) {
-			const changed = prListKey(record.value) !== prListKey(value);
-			record.value = value;
-			if (changed) notify(toplevel);
-		}
-		record.lastAttemptAt = Date.now();
-		record.inFlight = null;
-		return value;
-	})();
-	record.inFlight = inFlight;
-	prListState.set(toplevel, record);
-	return record.value;
-}
-
-/**
- * The one linked worktree a session badge may follow: exactly one entry other
- * than the checkout itself that is checked out on a branch with an OPEN PR.
- *
- * Exactly one, because the plugin cannot know which tree a session uses — DSH
- * records no session→worktree link at all — so an ambiguous repository stays on
- * its own checkout rather than guessing. A second open PR is a reason to say
- * nothing, not a reason to pick one. Detached, bare and prunable entries are
- * never candidates: they have no branch a PR could belong to.
- */
-function selectSessionWorktree(worktrees, openPrs, checkoutPath) {
-	if (openPrs === void 0 || openPrs.size === 0) return void 0;
-	const candidates = worktrees.filter((wt) =>
-		wt.path !== checkoutPath &&
-		wt.detached !== true &&
-		wt.bare !== true &&
-		wt.prunable !== true &&
-		typeof wt.branch === "string" &&
-		openPrs.has(wt.branch)
-	);
-	return candidates.length === 1 ? candidates[0] : void 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
@@ -522,6 +435,32 @@ function prStatusFor(toplevel, branch, notify) {
  * two-column XY status (X = index/staged, Y = worktree), `u` unmerged,
  * `?` untracked.
  */
+/** Relative path shortened to its last two segments — the hover-name contract. */
+function shortenPath(name) {
+	const parts = name.split("/");
+	return parts.length <= 2 ? name : parts.slice(-2).join("/");
+}
+
+/**
+ * Convert a remote URL to the hosted repo's WEB root: https stays https,
+ * `git@host:path` ssh syntax converts, a `.git` suffix is stripped. Null when
+ * the URL is neither form — the caller decides what a null is worth.
+ */
+function remoteToWebUrl(raw) {
+	const trimmed = raw.trim().replace(/\.git$/u, "");
+	const https = trimmed.match(/^https:\/\/([^/]+)\/(.+?)\/?$/u);
+	const ssh = trimmed.match(/^[^@]+@([^:]+):(.+)$/u);
+	const web = https !== null ? https[1] + "/" + https[2] : ssh !== null ? ssh[1] + "/" + ssh[2] : null;
+	if (web === null) return null;
+	try {
+		const url = new URL("https://" + web);
+		if (url.protocol === "https:" && url.pathname.length > 1) return url.origin + url.pathname.replace(/\/$/u, "");
+	} catch {
+		// not a URL we can vouch for
+	}
+	return null;
+}
+
 function parseStatusV2(out) {
 	let branch = "HEAD (detached)";
 	let upstream;
@@ -531,6 +470,9 @@ function parseStatusV2(out) {
 	let unstaged = 0;
 	let unmerged = 0;
 	let untracked = 0;
+	const untrackedNames = [];
+	const unstagedNames = [];
+	const stagedNames = [];
 	for (const line of out.split("\n")) {
 		if (line.startsWith("# branch.head ")) branch = line.slice(14).trim();
 		else if (line.startsWith("# branch.upstream ")) upstream = line.slice(18).trim();
@@ -543,12 +485,34 @@ function parseStatusV2(out) {
 			if (Number.isFinite(b)) behind = b;
 		} else if (line.startsWith("1 ") || line.startsWith("2 ")) {
 			// XY columns: X = index (staged), Y = worktree (unstaged)
-			if (line[2] !== ".") staged += 1;
-			if (line[3] !== ".") unstaged += 1;
+			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;
-		else if (line.startsWith("? ")) untracked += 1;
+		else if (line.startsWith("? ")) {
+			untracked += 1;
+			// `-uall` prints one `? <path>` per untracked FILE, so the names are
+			// the lines themselves — collected untruncated here and capped by the
+			// caller, so the hover's "and k more" arithmetic stays honest.
+			const name = line.slice(2).trim();
+			if (name !== "") untrackedNames.push(name);
+		}
 	}
-	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked };
+	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked, untrackedNames, unstagedNames, stagedNames };
 }
 
 /**
@@ -678,60 +642,136 @@ const OPERATION_NEXT = {
 };
 
 /**
- * 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):
+ * The configurable action ranking. Every rule carries a category; the order
+ * 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"] }
+ *
+ * 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`.
+ */
+const DEFAULT_NEXT_ORDER = ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"];
+
+/** Normalise any order list: known categories first, then the rest in default order. */
+function normalizeOrder(order) {
+	if (!Array.isArray(order)) return DEFAULT_NEXT_ORDER;
+	const known = order.filter((cat) => DEFAULT_NEXT_ORDER.includes(cat));
+	return [...known, ...DEFAULT_NEXT_ORDER.filter((cat) => !known.includes(cat))];
+}
+
+/** The settings namespace this plugin owns — its order lives there, live. */
+const SETTINGS_NS = "git-badge";
+
+/**
+ * The namespace schema, built from the host-provided schema lib — imported
+ * LAZILY because this plugin's module graph must load without it (the test
+ * suite runs from a bare checkout, and a host without the settings stack should
+ * lose only the settings card, never the badge).
+ */
+function orderSettingsSchema(Schema) {
+	return Schema.object({
+		order: Schema.array(Schema.union(DEFAULT_NEXT_ORDER)).default(DEFAULT_NEXT_ORDER)
+	});
+}
+
+/**
+ * The pre-settings override file. Still honoured as the namespace's BASE (a
+ * composition default, so a user who configured the JSON keeps their order
+ * after the upgrade) and as a fallback when the settings service is absent.
+ */
+function legacyOrderFile() {
+	try {
+		const home = process.env.DSH_HOME || join(process.env.HOME || "", ".dsh");
+		const raw = JSON.parse(readFileSync(join(home, "git-badge-next.json"), "utf8"));
+		return normalizeOrder(raw?.order);
+	} catch {
+		return DEFAULT_NEXT_ORDER;
+	}
+}
+
+/**
+ * The live order — one in-memory value, updated by the settings scope. It is
+ * authoritative only once the namespace actually registered; until then (and on
+ * a host without the settings stack, or in a unit test that never calls apply)
+ * the legacy file is read per call, which is the pre-settings behaviour.
+ */
+let currentOrder = DEFAULT_NEXT_ORDER;
+let settingsOrderActive = false;
+
+/** The ranking order every status read uses. */
+function nextOrder() {
+	return settingsOrderActive ? currentOrder : legacyOrderFile();
+}
+
+/**
+ * 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 } —
+ * what the invocation DOES, why THIS checkout justifies it now), ranked. Pure
+ * derivation over fields the status response already carries — no extra git
+ * 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
+ * example, rank "commit" above "sync" without touching code. Ties keep
+ * collection order.
  *
- *   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
+ * The new rules this generation adds:
+ *   - diverged (ahead AND behind) → `sync`: reconciling means rebase-then-push,
+ *     which the agent must confirm step by step — a plain pull would discard
+ *     the local-commit context
+ *   - merge-ready (`pr.mergeState === "CLEAN"`, GitHub's own verdict, or checks
+ *     passing + review approved) → `merge <n>`: the endgame action the old
+ *     table could never see
  *
  * 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.
+ * "no suggestion" is also a suggestion.
  *
- * @returns {{ command: string|undefined, why: string } | null}
+ * @returns {{ args: string, command: string|undefined, why: string, what: 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");
+	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;
+	const dirty = staged + unstaged + untracked;
+	const rules = [];
+	const add = (cat, args, why, what, command) => rules.push({ cat, args, why, what, command });
+
 	if (info.operation !== void 0 && info.operation !== null) {
 		const op = String(info.operation);
-		return {
-			command: OPERATION_NEXT[op],
-			why: unmerged > 0
+		add("operation", "next",
+			unmerged > 0
 				? `${unmerged} unmerged file${plural(unmerged)} blocking the paused ${op}`
-				: `a ${op} is paused mid-operation`
-		};
+				: `a ${op} is paused mid-operation`,
+			`resume the paused ${op}`,
+			OPERATION_NEXT[op]);
 	}
 	if (unmerged > 0) {
-		return { command: "git status", why: `${unmerged} unmerged file${plural(unmerged)} to resolve` };
+		add("unmerged", "next", `${unmerged} unmerged file${plural(unmerged)} to resolve`, "resolve the unmerged files (with you)", "git status");
 	}
-	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"}` };
+	if (behind > 0 && ahead > 0) {
+		add("sync", "sync", `${ahead} ahead, ${behind} behind — diverged`, "rebase your commits onto upstream and push (asks before any force)");
+	} else if (behind > 0) {
+		add("sync", "pull", `${behind} behind ${info.upstream ?? "upstream"}`, "update this branch from upstream", "git pull --ff-only");
 	}
-	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 (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}`);
+	} else if (ahead > 0) {
+		add("publish", "push", `${ahead} ahead of ${info.upstream ?? "upstream"}`, "push local commits to the remote", "git push");
 	}
-	if (ahead > 0) {
-		return { command: "git push", why: `${ahead} ahead of ${info.upstream ?? "upstream"}` };
+	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)`);
 	}
-	if (staged + unstaged + untracked > 0) {
-		const why = [
+	if (dirty > 0) {
+		const parts = [
 			staged > 0 ? `${staged} staged` : null,
 			unstaged > 0 ? `${unstaged} unstaged` : null,
 			untracked > 0 ? `${untracked} untracked` : null
@@ -741,12 +781,20 @@ function nextStep(info) {
 			: untracked > 0 && unstaged === 0
 				? "git add -A && git commit"
 				: "git add -p && git commit";
-		return { command, why: `work to commit: ${why}` };
+		add("commit", "commit", `work to commit: ${parts}`, staged > 0 ? "commit the staged changes" : "stage and commit the working changes", command);
 	}
-	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}` };
+	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`);
 	}
-	return null;
+	if (rules.length === 0) return null;
+
+	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 };
 }
 
 /**
@@ -850,16 +898,103 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		behind: parsed.behind
 	};
 	if (wantDetail) {
-		// last 3 commits (subject + relative age) for the planned hover card
-		const logOut = await runGit(toplevel, ["log", "-3", "--format=%h%x09%s%x09%cr"]);
-		if (logOut.stdout !== null && logOut.stdout.trim() !== "") {
-			info.lastCommits = logOut.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);
+		// 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;
+		}
+		// 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
+		// first". One rev-list --left-right, hover-gated like everything here,
+		// absent entirely when both are zero (in sync needs no row).
+		// The repo's WEB URL — the branch hover links the branch name to the
+		// compare view (`<repo>/compare/<base>...<branch>`), and that URL must be
+		// vouched for like pr.url is: http(s) only, rebuilt from the parsed parts
+		// so no payload value can reach an anchor as a scheme. Derived from
+		// `remote get-url origin` with ssh syntax converted; absent when there is
+		// no origin or the URL is not recognisably a hosted repo.
+		// These reads are independent — one batch, so hover latency is the
+		// longest call rather than their sum. The only dependent call (the
+		// left-right count needs a probed base ref) runs after the batch and
+		// tolerates its own failure.
+		const [remoteUrl, probeMain, probeMaster, logOut2, stashOut] = await Promise.all([
+			runGit(toplevel, ["remote", "get-url", "origin"]),
+			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/main"]),
+			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/master"]),
+			runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", "HEAD"]),
+			runGit(toplevel, ["stash", "list"])
+		]);
+		if (remoteUrl.stdout !== null && remoteUrl.stdout.trim() !== "") {
+			info.repoUrl = remoteToWebUrl(remoteUrl.stdout);
+		}
+		const 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) {
+			const baseName = baseRef.replace(/^origin\//u, "");
+			try {
+				const compare = new URL(info.repoUrl + "/compare/" + encodeURIComponent(baseName) + "..." + encodeURIComponent(info.branch));
+				if (compare.protocol === "https:") info.compareUrl = compare.href;
+			} catch {
+				// absent rather than wrong
+			}
+		}
+		if (baseRef !== null) {
+			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)) {
+				info.mainAhead = mAhead;
+				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 {
+			const plainOut = await runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", "HEAD"]);
+			if (plainOut.stdout !== null && plainOut.stdout.trim() !== "") {
+				info.branchCommits = plainOut.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);
+			}
 		}
-		// stash count, only surfaced when nonzero
-		const stashOut = await runGit(toplevel, ["stash", "list"]);
 		if (stashOut.stdout !== null) {
 			const count = stashOut.stdout.split("\n").filter((l) => l.trim() !== "").length;
 			if (count > 0) info.stashCount = count;
@@ -1149,10 +1284,10 @@ function watchWorkspace(root, key, workspaceId) {
 }
 
 /**
- * Workspace path -> { worktreePath, workspaceId, owned } for the inferred
- * worktree a session badge is currently following. One per workspace: selection
- * is a single choice by construction (selectSessionWorktree), so following a
- * different tree retires the previous one here.
+ * Workspace path -> { worktreePath, workspaceId, owned } for the worktree a
+ * session badge is currently following. One per workspace: a session follows at
+ * most one tree, so following a different tree (or none) retires the previous
+ * entry here.
  */
 const selectedWorktrees = new Map();
 
@@ -1266,48 +1401,117 @@ async function resolveWorkspace(ctx, params) {
 	return { status: 404, error: { code: "session-not-found", message: "no registered workspace owns that session" } };
 }
 
+/**
+ * The checkout a session registered for itself, or undefined.
+ *
+ * This is the ONLY source for "which worktree is this session using", and it has
+ * to be explicit: DSH records no session→worktree link (a session's cwd is
+ * immutable creation metadata and always the main checkout), so nothing in the
+ * host can answer it. The agent writes the registration with
+ * `dsh-git-badge-checkout <path>`; the file is advisory, so it is validated
+ * here before it is believed — the path must be a worktree git itself lists,
+ * the entry must be fresher than SESSION_CHECKOUT_TTL_MS, and the name/branch
+ * come from git rather than from the file. A stale, hand-edited or removed
+ * registration can therefore only fail to resolve, never point the badge at a
+ * directory that is not a worktree of this repository.
+ */
+function sessionCheckouts() {
+	if (typeof config.sessionCheckoutsFile === "string") {
+		try {
+			const raw = JSON.parse(readFileSync(config.sessionCheckoutsFile, "utf8"));
+			return raw !== null && typeof raw === "object" && typeof raw.sessions === "object" && raw.sessions !== null
+				? raw.sessions
+				: {};
+		} catch {
+			return {};
+		}
+	}
+	return readSessionCheckouts();
+}
+
+async function registeredCheckout(target, sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return void 0;
+	const entry = sessionCheckouts()[sessionId];
+	if (entry === void 0 || typeof entry?.path !== "string") return void 0;
+	const at = Date.parse(String(entry.at ?? ""));
+	if (!Number.isFinite(at) || Date.now() - at > SESSION_CHECKOUT_TTL_MS) return void 0;
+	const { toplevel, worktrees } = await worktreesFor(target.path);
+	// Git lists the main worktree first, and a registration only means something
+	// when the session's own directory IS that main checkout: a session already
+	// inside a linked worktree is its own answer and is never swapped sideways.
+	const main = worktrees[0];
+	if (toplevel === "" || main === void 0 || main.path !== toplevel || target.path !== toplevel || worktrees.length <= 1) return void 0;
+	const found = worktrees.find((tree) => tree.path === entry.path);
+	if (found === void 0 || found.path === toplevel) return void 0;
+	return { path: found.path, name: found.name, branch: found.branch };
+}
+
 /**
  * The directory a request is ABOUT.
  *
- * A SESSION-targeted chip may follow the one linked worktree its repository can be
- * shown to be working in (selectSessionWorktree): DSH records no session→worktree
- * link at all — session cwd is immutable creation metadata and `attachSession`
- * requires it to equal the workspace path — so a conversation started in the main
- * checkout would otherwise report `main` while its work, and its pull request,
- * live in a tree. The tree's watcher is reconciled HERE, because this is the only
- * place that knows which tree was chosen.
+ * A SESSION-targeted chip follows the checkout that session REGISTERED — the one
+ * signal that knows where the agent is actually working. Without a registration
+ * the request stays on the session's own directory: the plugin never guesses a
+ * worktree from pull requests (an earlier build inferred one from the branch
+ * with the open PR; the guess was invisible to the session that made it and
+ * silently wrong whenever two trees were in play).
  *
  * A WORKSPACE-targeted row never follows a worktree: a row surveys the checkout
  * the registry owns, and substituting a tree would make the row lie about the
  * branch it is on.
- *
- * Gated three ways so the common case costs nothing: the caller must name a
- * session, must be asking about PR state at all (selection is defined by an open
- * PR, so a caller not asking cannot benefit), and the repository must actually
- * have a linked worktree. Only then is the forge consulted.
  */
-async function effectiveTarget(target, bySession, wantPr, notify) {
-	if (bySession !== true || wantPr !== true || config.worktreeStatus === "off") return { id: target.id, path: target.path };
-	const { toplevel, worktrees } = await worktreesFor(target.path);
-	// Git lists the main worktree first, so `main.path === toplevel` is the exact
-	// test for "the session's own directory is the main checkout". A session whose
-	// directory IS a linked worktree is its own answer and is never swapped
-	// sideways onto a sibling.
-	const main = worktrees[0];
-	if (toplevel === "" || main === void 0 || main.path !== toplevel || worktrees.length <= 1) {
-		selectWorktreeWatch(target.path, target.id, void 0);
-		return { id: target.id, path: target.path };
+async function effectiveTarget(target, sessionId) {
+	const bySession = typeof sessionId === "string" && sessionId !== "";
+	if (config.worktreeStatus !== "off") {
+		const registered = bySession ? await registeredCheckout(target, sessionId) : void 0;
+		if (registered !== void 0) {
+			selectWorktreeWatch(target.path, target.id, registered.path);
+			// The name and branch travel; the PATH never does (AGENTS.md rule 7).
+			return { id: target.id, path: registered.path, worktree: { name: registered.name, branch: registered.branch } };
+		}
 	}
-	const openPrs = openPrsFor(toplevel, notify);
-	const chosen = selectSessionWorktree(worktrees, openPrs, toplevel);
-	selectWorktreeWatch(target.path, target.id, chosen === void 0 ? void 0 : chosen.path);
-	if (chosen === void 0) return { id: target.id, path: target.path };
-	// The name and branch travel; the PATH never does (AGENTS.md rule 7).
-	return { id: target.id, path: chosen.path, worktree: { name: chosen.name, branch: chosen.branch } };
+	// No registration (or a stale one): retire any follow this workspace had, so
+	// clearing the registration actually stops the extra watcher.
+	selectWorktreeWatch(target.path, target.id, void 0);
+	return { id: target.id, path: target.path };
 }
 
 /** Host plugin body — register the status route and the SSE change feed. */
 function apply(ctx) {
+	// 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
+	// with no file poll and no restart. The pre-settings JSON file, when it
+	// exists, seeds the namespace as its composition BASE so an order configured
+	// before this existed survives the upgrade; it is also the fallback when the
+	// settings service is absent (a host composed without dsh-settings).
+	currentOrder = legacyOrderFile();
+	if (typeof ctx.inject === "function") {
+		try {
+			ctx.inject(["settings"], async (settingsCtx) => {
+				let Schema;
+				try {
+					Schema = await config.settingsSchemaLoader();
+				} catch (error) {
+					console.error("[dsh-git-badge] schema lib unavailable; keeping the legacy order file:", error);
+					return;
+				}
+				const scope = settingsCtx.settings.register(SETTINGS_NS, orderSettingsSchema(Schema), {
+					base: { order: legacyOrderFile() }
+				});
+				currentOrder = normalizeOrder(scope.get()?.order);
+				settingsOrderActive = true;
+				settingsCtx.effect(() => scope.watch((next) => {
+					currentOrder = normalizeOrder(next?.order);
+				}), "dsh-git-badge: order settings");
+				settingsCtx.effect(() => () => {
+					settingsOrderActive = false;
+				}, "dsh-git-badge: order settings teardown");
+			});
+		} catch (error) {
+			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
@@ -1332,7 +1536,7 @@ function apply(ctx) {
 				// session's own directory — see effectiveTarget. A workspace-targeted
 				// row never leaves the checkout the registry owns.
 				const session = url.searchParams.get("session");
-				const effective = await effectiveTarget(target, session !== null && session !== "", pr, notifyChange);
+				const effective = await effectiveTarget(target, session ?? void 0);
 				const info = await gitStatus(effective.path, detail, pr);
 				const body = { ...info, workspace: target.id };
 				if (effective.worktree !== void 0 && info.git === true) {
@@ -1340,7 +1544,7 @@ function apply(ctx) {
 					// name. Saying so is the whole honesty of the feature: the chip's
 					// mark says "worktree", its name says which, and this flag tells the
 					// card why the checkout below differs from the branch beside it.
-					body.worktreeInferred = true;
+					body.worktreeFollowed = true;
 					if (detail) {
 						// The session's OWN directory, for the card's `checkout` row, so the
 						// main checkout stays visible once the badge follows a tree. Gated
@@ -1461,10 +1665,6 @@ export {
 	summarizeChecks,
 	prStatusFor,
 	prState,
-	readOpenPrs,
-	openPrsFor,
-	prListState,
-	selectSessionWorktree,
 	selectWorktreeWatch,
 	selectedWorktrees,
 	statusInFlight,