dsh-git-badge 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -10,6 +10,47 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-09-16
+
+### Added
+
+- **A session now tells the badge which checkout it is working in.** dsh cannot
+  supply that fact — a session's `cwd` is immutable creation metadata and always
+  the main checkout — so the agent registers it explicitly:
+  `npx dsh-git-badge-checkout <path>` (shipped bin), run by the `git-worktree`
+  skill after `git worktree add` and by `/gh checkout` when a switch lands in or
+  out of a linked worktree. The node half prefers the registration, and
+  validates it: git's own worktree list must know the path, the entry expires
+  after 24h, and the name/branch come from git, never from the file. The
+  registration is self-clearing — removing it (or letting it expire) retires the
+  extra watcher and the badge returns to the session's own directory.
+
+- **A settings card for the ranking order: Settings → Plugins → Git Badge.**
+  The order now lives in this plugin's own `git-badge` settings namespace —
+  declared with a schema, validated and stored by the host, observed live — and
+  the card reorders the seven categories with up/down controls, Save/Discard,
+  and Reset to default. No file polling, no restart: a change applies to the
+  next status read. A pre-existing `~/.dsh/git-badge-next.json` seeds the
+  namespace as its base (and remains the fallback on hosts without the settings
+  stack), so an order configured before the card existed survives the upgrade.
+  `/gh order` still works for agent-driven changes.
+
+### Changed
+
+- **The ranking card sits in an expander, like the host's other plugin cards.**
+  Collapsed by default with the title and a one-line description; the list,
+  reorder controls, and Save/Discard/Reset live in the body, which auto-collapses
+  once a save settles clean. The card chrome reproduces the host's plugin-card
+  values inline (its CSS module is not exported to plugins), so it reads as one
+  of the set rather than loose content between it.
+
+- **PR inference is gone.** The badge no longer guesses a worktree from the
+  branch with an open pull request. The guess was invisible to the session that
+  made it and silently wrong whenever two trees were in play; a `worktreeInferred`
+  marker, the repository-wide `gh pr list` read that powered it, and the
+  inference wording in the hover all go with it. A session follows its
+  registration or stays on its own checkout — nothing else.
+
 ## [0.15.0] - 2026-09-15
 
 ### Changed

package/README.md

@@ -5,13 +5,13 @@ Git status badges for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek
 - **Input-row chip** — `● main ↑0 ↓2 ✎3` next to the access picker, showing the git state of the workspace the current conversation is attached to. Works on every install.
 - **Hover card** — rest a pointer on the chip for what won't fit: the file breakdown (`✎3` split into staged / unstaged / untracked), the last three commits, and the stash. Fetched only on hover, so the everyday badge pays nothing for it. Works on every install.
 - **PR / CI token** — `● main ↑0 ↓2 PR#142 ✗` when the branch has a GitHub pull request, read through your own `gh` CLI (the plugin never handles a credential). The token **links to the PR** — it opens in a new tab, and underlines when you hover or focus it. Invisible when `gh` cannot answer: not installed, not logged in, no GitHub remote, offline or rate-limited all render the unchanged chip, and a token with no URL to link to stays plain text.
-- **Worktree-aware** — a conversation's directory is fixed when it is created, so a conversation that does its work in a linked `git worktree` would otherwise keep reporting the main checkout. When exactly one linked worktree of that repository has an open pull request, the badge describes **that worktree** instead — its branch, counts, tree mark and PR/CI token (`🌳 chore/global-skills-tiering ↑0 ↓2 PR#391 ✓` rather than `● main`). The hover card names the tree in a `worktree` row, says it was inferred, and adds a `checkout` row with the conversation's own directory, so the main checkout's branch and dirty state stay one hover away. One candidate only — two open PRs across worktrees is a reason to say nothing rather than guess — and a session row always reports the checkout that session is working in.
+- **Worktree-aware** — a conversation's directory is fixed when it is created, so a conversation that does its work in a linked `git worktree` would otherwise keep reporting the main checkout. The session registers its checkout (`npx dsh-git-badge-checkout <path>`, run by the git-worktree and `/gh checkout` paths), and the badge describes **that worktree** instead — its branch, counts, tree mark and PR/CI token (`🌳 chore/global-skills-tiering ↑0 ↓2 PR#391 ✓` rather than `● main`). The hover card names the tree in a `worktree` row and adds a `checkout` row with the conversation's own directory, so the main checkout's branch and dirty state stay one hover away. Registrations are advisory: git's own worktree list validates the path, entries expire after 24h, and a workspace-targeted row always reports the checkout the registry owns.
 - **Sidebar session-row action token** — each session row shows the ONE thing that conversation needs from you, or nothing at all: `merge`, `fix CI`, `review`, `resolve`, `pull`, `push`. It is triage rather than status: `merge` appears only when GitHub itself reports `mergeStateStatus: CLEAN`, and every waiting state (draft, blocked, behind, checks still running) stays silent. Hovering the row adds a line naming the checkout and the pull request the action refers to. The token floats to the right of the row, is set heavier than the timestamp beside it, and is coloured by how much it needs you — red for a conflict or a failing build, amber for a requested review, green for `merge`, quiet grey for routine sync. Requires the `sidebar.workspaces.sessionRow` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
 - **Nothing on workspace rows.** A workspace cannot know which worktree its conversations are using, so a per-workspace badge could only guess or report the main checkout. The seam is on the session row for that reason.
 
 The leading **mark** belongs to the input chip: a circle filled with the status colour, or a **tree** when the checkout is a linked `git worktree`. The sidebar row deliberately carries no mark — see the row bullet above, where one word does the job a colour cannot. (`●`/`🌳` stand in for it here — it is a drawn SVG so that it can take the theme's status colours.)
 
-Event-driven freshness: working trees are watched and updates push over SSE — badges flip within ~1s of any commit, stage, or edit, including inside a linked worktree that is only inferred. One `git status --porcelain=v2` per sample, shared by every surface pointing at the same checkout, plus at most one `gh` read per repository-and-branch per ~90s and one repository-wide open-PR list per ~90s. The status API takes **no path**: the caller passes a session id (chip and sidebar rows) or a workspace id, and the server resolves the directory itself.
+Event-driven freshness: working trees are watched and updates push over SSE — badges flip within ~1s of any commit, stage, or edit, including inside a linked worktree the session registered. One `git status --porcelain=v2` per sample, shared by every surface pointing at the same checkout, plus at most one `gh` read per repository-and-branch per ~90s. The status API takes **no path**: the caller passes a session id (chip and sidebar rows) or a workspace id, and the server resolves the directory itself.
 
 Diagrams, the hover card's full field list and a walkthrough for git newcomers live
 in the [repo README](https://github.com/Kevin-McIsaac/dsh-workspace-git-badge) —

package/lib/client.js

@@ -436,9 +436,9 @@ window.__ModuleLoader__.load({
 				"aria-label":
 					(isWorktree ? "git worktree: " : "git: ") +
 					STATUS_LABEL[status] +
-					// an inferred checkout is not where the conversation lives, so the
-					// accessible name says where the fact came from
-					(info.worktreeInferred === true ? " (inferred from an open pull request in this repository)" : ""),
+					// a followed checkout is not where the conversation lives, and the
+					// accessible name says so — the session registered it explicitly
+					(info.worktreeFollowed === true ? " (registered for this session)" : ""),
 				focusable: "false",
 				style: { flex: "none", display: "block", color: META_STYLE.color }
 			};
@@ -585,7 +585,7 @@ window.__ModuleLoader__.load({
 				const checkout = [name === "" ? String(info.branch) : name + " on " + info.branch];
 				// the node half followed this tree because it is the one whose branch
 				// has the open PR — say so, because nothing on the row can
-				if (info.worktreeInferred === true) checkout.push("its branch has the open pull request");
+
 				bits.push("checkout: " + checkout.join(" \u00B7 "));
 			}
 			const pr = formatPrDetail(info.pr);
@@ -623,7 +623,7 @@ window.__ModuleLoader__.load({
 
 		/**
 		 * The `checkout` row: the directory the CONVERSATION itself names, present
-		 * only when the badge is describing an inferred worktree instead. The chip's
+		 * only when the badge is describing a FOLLOWED worktree instead. The chip's
 		 * branch and counts are the tree's in that case, so without this row the
 		 * checkout's own state is nowhere on screen. Branch, then files (or "clean"),
 		 * then sync counts only when they are nonzero — the chip's own rule.
@@ -642,15 +642,13 @@ window.__ModuleLoader__.load({
 		 * The `worktree` row: WHICH linked worktree the badge is describing. The chip
 		 * names only the branch (see the note above formatOperationToken), so the
 		 * card is the one place a tree is identified — the mark's shape can only say
-		 * *that* the checkout is a worktree, never which. An inferred follow also says
-		 * why, because "which tree" and "why this tree" are different questions and
-		 * the second is the one a reader will ask.
+		 * *that* the checkout is a worktree, never which.
 		 */
 		function worktreeDetail(info) {
 			if (info === void 0 || info === null || info.isWorktree !== true) return void 0;
 			const name = typeof info.worktreeName === "string" ? info.worktreeName : "";
 			if (name === "") return void 0;
-			return info.worktreeInferred === true ? name + " (inferred from its open pull request)" : name;
+			return name;
 		}
 
 		const CARD_CONTAINER = {
@@ -820,6 +818,51 @@ 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 host's plugin-card chrome, reproduced inline: its CSS module is not
+		// exported to plugins, so these values mirror PluginCard.module.css so our
+		// card sits in the same list as its siblings.
+		const CARD_BASE = {
+			border: ".5px solid var(--dsw-alias-border-l4, #e4e8eb)",
+			borderRadius: "16px",
+			listStyle: "none",
+			transition: "border-color .16s, background .16s"
+		};
+		const CARD_CLOSED = { ...CARD_BASE, background: "var(--dsw-alias-bg-layer-3, #ffffff)" };
+		const CARD_OPEN = {
+			...CARD_BASE,
+			background: "var(--dsw-alias-bg-layer-2, #f7f8f9)",
+			borderColor: "var(--dsw-alias-label-dimmed, #b8bfc4)"
+		};
+		const CARD_HEADER = {
+			appearance: "none",
+			width: "100%",
+			font: "inherit",
+			color: "inherit",
+			textAlign: "left",
+			cursor: "pointer",
+			background: "none",
+			border: 0,
+			borderRadius: "12px",
+			display: "flex",
+			alignItems: "center",
+			gap: "12px",
+			padding: "14px 16px"
+		};
+		const CARD_NAME = { color: "var(--dsw-alias-label-primary, #1f2328)", fontSize: "15px", fontWeight: "600", lineHeight: "1.4" };
+		const CARD_DESCRIPTION = { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", fontSize: "13px", lineHeight: "1.5" };
+
+		const CARD_BUTTON = {
+			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"
+		};
+
 		/** One label/value row — the shape every hover body shares. */
 		function cardRow(label, value) {
 			return react_jsx_runtime.jsxs("div", {
@@ -868,10 +911,10 @@ window.__ModuleLoader__.load({
 			// the branch alone, so this row is the only place the tree is named.
 			add("worktree", worktreeDetail(data));
 			// The conversation's OWN directory, present only when the badge is
-			// describing an inferred worktree — the chip's branch and counts are the
+			// describing a followed worktree — the chip's branch and counts are the
 			// tree's in that case, so this is where the checkout's own state stays
 			// visible. Absent until the `detail=1` response lands, like commits/stash.
-			if (data.worktreeInferred === true) add("checkout", formatCheckoutDetail(data.checkout));
+			if (data.worktreeFollowed === true) add("checkout", formatCheckoutDetail(data.checkout));
 			add("stash", data.stashCount === void 0 ? void 0 : data.stashCount + " stashed");
 			return react_jsx_runtime.jsx("div", { style: CARD_CONTAINER, children: rows });
 		}
@@ -1172,6 +1215,162 @@ window.__ModuleLoader__.load({
 		// `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.
+		/** The built-in ranking order — what "Reset to default" restores. */
+		const DEFAULT_ORDER = ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"];
+
+		/**
+		 * Move one category within the ranking order — the card's only reorder
+		 * primitive, pure so the suite can drive it without a browser. Out-of-range
+		 * moves are no-ops (the buttons disable at the ends, this is the belt).
+		 */
+		function moveCategory(order, index, delta) {
+			const next = [...order];
+			const to = index + delta;
+			if (index < 0 || index >= next.length || to < 0 || to >= next.length) return next;
+			const [moved] = next.splice(index, 1);
+			next.splice(to, 0, moved);
+			return next;
+		}
+
+		/** Human labels for the ranking categories, in default order. */
+		const CATEGORY_LABELS = {
+			operation: ["operation", "resume a paused merge/rebase"],
+			unmerged: ["unmerged", "resolve conflict markers"],
+			sync: ["sync", "pull, or rebase + confirmed force-push"],
+			publish: ["publish", "push local commits"],
+			merge: ["merge", "a merge-ready pull request"],
+			commit: ["commit", "stage and commit working changes"],
+			checks: ["checks", "watch failing CI"]
+		};
+
+		/**
+		 * The settings card's body — Settings → Plugins → Git Badge. Reads the
+		 * bound settings scope through the store the registration injects and
+		 * writes back one field ("order") via the scope's mutate path. Styled like
+		 * this plugin's other surfaces rather than the host's card primitives,
+		 * which are not exported to plugins.
+		 */
+		function GitBadgeOrderCard(props) {
+			const state = props.useGitBadgeOrderCard((snapshot) => snapshot);
+			const t = props.t;
+			// Local expander state, mirroring the host's plugin cards: collapsed by
+			// default, and auto-collapsed again once a save settles clean (so the
+			// card confirms itself the way its siblings do).
+			const [open, setOpen] = react.useState(false);
+			const saveStarted = react.useRef(false);
+			react.useEffect(() => {
+				if (state.saving) {
+					saveStarted.current = true;
+					return;
+				}
+				if (!saveStarted.current) return;
+				saveStarted.current = false;
+				if (!state.dirty && !state.failed) setOpen(false);
+			}, [state.dirty, state.failed, state.saving]);
+			if (!state.available) return null;
+			const rows = state.order.map((cat, index) => {
+				const [label, hint] = CATEGORY_LABELS[cat] ?? [cat, ""];
+				return react_jsx_runtime.jsxs("div", {
+					style: { display: "flex", alignItems: "center", gap: "8px", padding: "2px 0" },
+					children: [
+						react_jsx_runtime.jsx("span", {
+							style: { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", fontFamily: "monospace", minWidth: "16px", textAlign: "right" },
+							children: String(index + 1)
+						}),
+						react_jsx_runtime.jsx("span", { style: { minWidth: "84px" }, children: label }),
+						react_jsx_runtime.jsx("span", { style: { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "1", minWidth: 0 }, children: hint }),
+						react_jsx_runtime.jsx("button", {
+							type: "button",
+							"aria-label": t("moveUp") + " " + label,
+							disabled: state.saving || !state.writable || index === 0,
+							onClick: () => props.move(index, -1),
+							style: CARD_BUTTON,
+							children: "\u2191"
+						}),
+						react_jsx_runtime.jsx("button", {
+							type: "button",
+							"aria-label": t("moveDown") + " " + label,
+							disabled: state.saving || !state.writable || index === state.order.length - 1,
+							onClick: () => props.move(index, 1),
+							style: CARD_BUTTON,
+							children: "\u2193"
+						})
+					]
+				}, cat);
+			});
+			// The card chrome matches the host's own plugin cards (its CSS module is
+			// not exported to plugins, so the values are reproduced inline): an <li>
+			// with the bordered card, a header button that expands, and a body that
+			// carries the list and the footer actions.
+			return react_jsx_runtime.jsxs("li", {
+				style: open ? CARD_OPEN : CARD_CLOSED,
+				children: [
+					react_jsx_runtime.jsxs("button", {
+						type: "button",
+						"aria-expanded": open,
+						"aria-label": t(open ? "collapse" : "expand") + ": " + t("title"),
+						onClick: () => setOpen(!open),
+						style: CARD_HEADER,
+						children: [
+							react_jsx_runtime.jsxs("span", {
+								style: { display: "flex", flexDirection: "column", flex: "1", gap: "4px", minWidth: 0 },
+								children: [
+									react_jsx_runtime.jsx("span", { style: CARD_NAME, children: t("title") }),
+									react_jsx_runtime.jsx("span", { style: CARD_DESCRIPTION, children: t("description") })
+								]
+							}),
+							react_jsx_runtime.jsx("span", {
+								"aria-hidden": true,
+								style: open
+									? { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", transform: "rotate(180deg)", transition: "transform .16s" }
+									: { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", transition: "transform .16s" },
+								children: (primitives !== null && primitives.IconChevronDownOutline14 !== void 0
+									? react_jsx_runtime.jsx(primitives.IconChevronDownOutline14, {})
+									: "\u25BE")
+							})
+						]
+					}),
+					open
+						? react_jsx_runtime.jsxs("div", {
+							style: { borderTop: ".5px solid var(--dsw-alias-border-l2, #e4e8eb)", margin: "0 16px", paddingBottom: "8px" },
+							children: [
+								react_jsx_runtime.jsx("div", { style: { padding: "10px 0 6px" }, children: t("intro") }),
+								react_jsx_runtime.jsx("div", { style: { display: "flex", flexDirection: "column" }, children: rows }),
+								react_jsx_runtime.jsxs("div", {
+									style: { display: "flex", gap: "8px", alignItems: "center", justifyContent: "flex-end", padding: "12px 0 4px" },
+									children: [
+										state.failed ? react_jsx_runtime.jsx("span", { style: { color: "var(--dsw-alias-label-error, #d13438)", flex: "1", fontSize: "12px" }, children: t("failed") }) : null,
+										state.writable ? null : react_jsx_runtime.jsx("span", { style: { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "1", fontSize: "12px" }, children: t("readOnly") }),
+										react_jsx_runtime.jsx("button", {
+											type: "button",
+											disabled: !state.dirty || state.saving,
+											onClick: props.discard,
+											style: CARD_BUTTON,
+											children: t("discard")
+										}),
+										react_jsx_runtime.jsx("button", {
+											type: "button",
+											disabled: !state.dirty || state.saving || !state.writable,
+											onClick: props.save,
+											style: CARD_BUTTON,
+											children: state.saving ? t("saving") : t("save")
+										}),
+										react_jsx_runtime.jsx("button", {
+											type: "button",
+											disabled: state.saving || !state.writable,
+											onClick: props.reset,
+											style: CARD_BUTTON,
+											children: t("reset")
+										})
+									]
+								})
+							]
+						})
+						: null
+				]
+			});
+		}
+
 		const inject = ["slots", "inputTriggers"];
 
 		/**
@@ -1267,6 +1466,126 @@ window.__ModuleLoader__.load({
 				});
 			}
 
+			// The settings card (Settings → Plugins → Git Badge): the order lives
+			// in this plugin's `git-badge` settings namespace, which the node half
+			// registers; this half renders the card that edits it through the bound
+			// scope — reads from the scope snapshot, writes one field via mutate.
+			// Guarded: a host without settingsScope loses the card, never the
+			// badges.
+			if (typeof ctx.inject === "function") {
+				try {
+					ctx.inject(["settingsScope", "slots", "locale"], (scopeCtx) => {
+						const NS = "dsh-git-badge";
+						scopeCtx.effect(() => scopeCtx.locale.register(NS, {
+							en: {
+								title: "Git Badge",
+								description: "Which action class the badge suggests first.",
+								expand: "Expand",
+								collapse: "Collapse",
+								intro: "The badge suggests one next action; this is the order it considers the classes in.",
+								save: "Save",
+								discard: "Discard",
+								reset: "Reset to default",
+								saving: "Saving\u2026",
+								failed: "save failed \u2014 try again",
+								readOnly: "read-only on this host",
+								moveUp: "Move up",
+								moveDown: "Move down"
+							}
+						}), "dsh-git-badge: settings locale");
+						const scope = scopeCtx.settingsScope.bind({ namespace: "git-badge" });
+						// draft === null means "mirror the stored order"; any reorder
+						// stages a copy, and only a confirmed write clears it — a
+						// rejected write leaves the draft for a retry rather than
+						// pretending it saved.
+						let draft = null;
+						let saving = false;
+						let failed = false;
+						const subscribers = new Set();
+						let snapshot = null;
+						const storedOrder = () => {
+							const view = scope.getSnapshot();
+							return Array.isArray(view?.value?.order) ? view.value.order : DEFAULT_ORDER;
+						};
+						const build = () => {
+							const view = scope.getSnapshot();
+							const stored = storedOrder();
+							const order = draft ?? stored;
+							return {
+								available: view?.status === "ready",
+								writable: view?.writable === true,
+								order,
+								dirty: draft !== null && draft.join() !== stored.join(),
+								saving,
+								failed
+							};
+						};
+						const publish = () => {
+							snapshot = build();
+							for (const listener of subscribers) listener();
+						};
+						scopeCtx.effect(() => {
+							const off = scope.subscribe(publish);
+							return () => {
+								if (typeof off === "function") off();
+							};
+						}, "dsh-git-badge: settings scope");
+						publish();
+						const store = {
+							getSnapshot: () => snapshot ?? build(),
+							subscribe: (listener) => {
+								subscribers.add(listener);
+								return () => subscribers.delete(listener);
+							}
+						};
+						const save = async () => {
+							if (draft === null || saving) return;
+							const wanted = [...draft];
+							saving = true;
+							failed = false;
+							publish();
+							try {
+								await scope.mutate([{ op: "set", path: ["order"], value: wanted }]);
+							} catch (error) {
+								console.error("[dsh-git-badge] order save failed:", error);
+							}
+							saving = false;
+							if (storedOrder().join() === wanted.join()) draft = null;
+							else failed = true;
+							publish();
+						};
+						scopeCtx.slots.inject("settings.plugin.item", function* () {
+							yield scopeCtx.slots.register({
+								name: "settings.plugin.item",
+								key: "git-badge",
+								locale: NS,
+								inject: () => ({
+									hooks: { gitBadgeOrderCard: store },
+									move: (index, delta) => {
+										draft = moveCategory(draft ?? [...storedOrder()], index, delta);
+										failed = false;
+										publish();
+									},
+									save: () => void save(),
+									discard: () => {
+										draft = null;
+										failed = false;
+										publish();
+									},
+									reset: () => {
+										draft = [...DEFAULT_ORDER];
+										failed = false;
+										publish();
+									}
+								})
+							}, GitBadgeOrderCard);
+						});
+					});
+				} catch (error) {
+					console.error("[dsh-git-badge] settings card unavailable:", 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
@@ -1348,7 +1667,7 @@ window.__ModuleLoader__.load({
 		// Additive; the host reads apply/inject and ignores the rest. The suite
 		// drives these to assert the REQUEST contract — which surface asks for the
 		// expensive extras — without a browser, a fetch or a network.
-		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken, ghSkillActions };
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken, ghSkillActions, moveCategory };
 		return module.exports;
 	}
 });

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
@@ -741,19 +654,57 @@ const OPERATION_NEXT = {
  */
 const DEFAULT_NEXT_ORDER = ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"];
 
-/** The ranking override file — read per call (one tiny stat+read per status). */
-function nextOrder() {
+/** 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"));
-		if (!Array.isArray(raw?.order)) return DEFAULT_NEXT_ORDER;
-		const known = raw.order.filter((cat) => DEFAULT_NEXT_ORDER.includes(cat));
-		return [...known, ...DEFAULT_NEXT_ORDER.filter((cat) => !known.includes(cat))];
+		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 } —
@@ -1333,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();
 
@@ -1450,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
@@ -1516,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) {
@@ -1524,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
@@ -1645,10 +1665,6 @@ export {
 	summarizeChecks,
 	prStatusFor,
 	prState,
-	readOpenPrs,
-	openPrsFor,
-	prListState,
-	selectSessionWorktree,
 	selectWorktreeWatch,
 	selectedWorktrees,
 	statusInFlight,

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.15.0",
+  "version": "0.16.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",
   "bin": {
-    "dsh-git-badge-seam": "seam/apply.js"
+    "dsh-git-badge-seam": "seam/apply.js",
+    "dsh-git-badge-checkout": "seam/checkout.js"
   },
   "exports": {
     ".": "./lib/index.js",
@@ -56,10 +57,14 @@
     "package.json",
     "seam/anchors.js",
     "seam/apply.js",
+    "seam/checkout.js",
     "seam/postinstall.js",
     "seam/skill.js",
     "seam/store.js",
     "seam/stub-index.js",
     "skill/gh/SKILL.md"
-  ]
+  ],
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  }
 }

package/seam/checkout.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * dsh-git-badge-checkout — tell the badge which checkout THIS session is working
+ * in.
+ *
+ * WHY THIS EXISTS: a dsh session's cwd is immutable creation metadata — it is
+ * the main checkout forever, even after the agent does its work in a linked
+ * worktree. The badge therefore cannot know, on its own, that a session moved
+ * into `.wt/<name>`; it can only infer a worktree from an open pull request.
+ * This command closes that gap: the agent registers the checkout explicitly, and
+ * the node half prefers the registration over inference.
+ *
+ * The registration is advisory and self-expiring (24h) — never let it fail the
+ * work that earned it:
+ *
+ *   usage:  npx dsh-git-badge-checkout <path>     register this session
+ *           npx dsh-git-badge-checkout --clear    forget this session
+ *
+ * The path is validated as a real worktree of its repository before it is
+ * written, so a typo cannot point the badge at an unrelated directory.
+ */
+import { execFileSync } from "node:child_process";
+import { basename, resolve } from "node:path";
+import { clearSessionCheckout, writeSessionCheckout } from "./store.js";
+
+function usage(message) {
+	if (message !== void 0) console.error(message);
+	console.error("usage: dsh-git-badge-checkout <path> | --clear");
+}
+
+/** Worktree paths git lists for the repo containing `dir`. */
+function worktreePaths(dir) {
+	const out = execFileSync("git", ["-C", dir, "worktree", "list", "--porcelain"], { encoding: "utf8" });
+	return out
+		.split("\n")
+		.filter((line) => line.startsWith("worktree "))
+		.map((line) => resolve(line.slice("worktree ".length).trim()));
+}
+
+function branchOf(dir) {
+	try {
+		return execFileSync("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).trim();
+	} catch {
+		return "unknown";
+	}
+}
+
+const sessionId = process.env.DSH_SESSION_ID;
+if (sessionId === void 0 || sessionId === "") {
+	usage("no DSH_SESSION_ID in the environment — run this from inside a dsh session.");
+	process.exit(2);
+}
+
+const arg = process.argv[2];
+if (arg === "--clear") {
+	clearSessionCheckout(sessionId);
+	console.log("[dsh-git-badge] checkout registration cleared for this session.");
+	process.exit(0);
+}
+if (arg === void 0 || arg === "") {
+	usage();
+	process.exit(2);
+}
+
+const path = resolve(arg);
+let paths;
+try {
+	paths = worktreePaths(path);
+} catch (error) {
+	console.error(`[dsh-git-badge] ${path} is not a git worktree: ${String(error?.message ?? error)}`);
+	process.exit(1);
+}
+if (!paths.includes(path)) {
+	console.error(`[dsh-git-badge] ${path} is not a worktree of its repository (git lists: ${paths.join(", ")})`);
+	process.exit(1);
+}
+
+if (!writeSessionCheckout(sessionId, path)) {
+	console.error("[dsh-git-badge] could not write the registration; the badge keeps its inferred checkout.");
+	process.exit(1);
+}
+console.log(`[dsh-git-badge] this session's checkout is now ${basename(path)} (${branchOf(path)}).`);

package/seam/store.js

@@ -1,4 +1,13 @@
 /**
+ * Two out-of-band stores live here, both keyed files under dataDir():
+ *
+ *   restart-pending.json    install/applied a host patch → the UI offers a restart
+ *   session-checkouts.json  which checkout a SESSION is working in — the one
+ *                           fact dsh cannot supply (a session's cwd is immutable
+ *                           creation metadata and always the main checkout, so a
+ *                           session working in a linked worktree is invisible
+ *                           without an explicit registration)
+ *
  * The restart-pending marker — the bridge from install-time (node side) to the
  * running UI.
  *
@@ -68,4 +77,60 @@ export function clearRestartMarker() {
 	} catch {
 		// Absent is the goal; any error leaves the marker to be cleared later.
 	}
-}
+}
+/** How long a session-checkout registration stays trustworthy. */
+export const SESSION_CHECKOUT_TTL_MS = 24 * 60 * 60 * 1000;
+
+function sessionCheckoutsPath() {
+	return join(dataDir(), "session-checkouts.json");
+}
+
+/** Every registration, `{ sessionId: { path, at } }`. Never throws. */
+export function readSessionCheckouts() {
+	try {
+		if (!existsSync(sessionCheckoutsPath())) return {};
+		const raw = JSON.parse(readFileSync(sessionCheckoutsPath(), "utf8"));
+		return raw !== null && typeof raw === "object" && typeof raw.sessions === "object" && raw.sessions !== null
+			? raw.sessions
+			: {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Register the checkout a session is working in. Written by the agent (the
+ * git-worktree and /gh checkout paths), read by the node half.
+ */
+export function writeSessionCheckout(sessionId, path) {
+	try {
+		mkdirSync(dataDir(), { recursive: true });
+		const sessions = readSessionCheckouts();
+		sessions[sessionId] = { path, at: new Date().toISOString() };
+		writeFileSync(
+			sessionCheckoutsPath(),
+			JSON.stringify({ schema: "dsh-git-badge/session-checkout/v1", sessions }),
+			"utf8",
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Forget one session's registration (worktree removed, or the session left). */
+export function clearSessionCheckout(sessionId) {
+	try {
+		const sessions = readSessionCheckouts();
+		if (!(sessionId in sessions)) return true;
+		delete sessions[sessionId];
+		writeFileSync(
+			sessionCheckoutsPath(),
+			JSON.stringify({ schema: "dsh-git-badge/session-checkout/v1", sessions }),
+			"utf8",
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/skill/gh/SKILL.md

@@ -79,12 +79,23 @@ unstaged / untracked / unmerged), plus any in-progress operation marker
   what is dirty and confirm the switch when work would carry over. Unknown
   branch → say so and list the closest local names.
 
+  If the switch lands you in — or out of — a linked worktree, register where you
+  are so the session badge follows the right checkout:
+  `npx dsh-git-badge-checkout "$(git rev-parse --show-toplevel)"` (best effort;
+  ignore failure). Clearing back to the main checkout is the same command run
+  against the main worktree — the badge treats the main checkout as the default.
+  A session's cwd is fixed at creation, so this registration is the ONLY signal
+  the badge has.
+
 - **`/gh order`** — reconfigure which action class the badge ranks first. The
-  order is one line of JSON at `~/.dsh/git-badge-next.json`:
-  `{ "order": ["operation", "unmerged", "sync", "publish", "merge", "commit",
-  "checks"] }` — any subset, any order; unlisted categories rank after in
-  default order. Read the file (it may not exist yet), apply the requested
-  change, show the resulting order, and never invent categories. Typical
+  order lives in the `git-badge` settings namespace, edited in the UI at
+  **Settings → Plugins → Git Badge** (an ordered list with up/down controls).
+  When the request comes through the agent instead, read the current value from
+  the settings document (`~/.dsh/settings.yaml`, the `git-badge:` section) and
+  change that `order` list — any subset, any order; unlisted categories rank
+  after in default order. Never invent categories. The older
+  `~/.dsh/git-badge-next.json` is only a fallback for hosts without the
+  settings stack; do not edit it when the namespace is present. Typical
   invocations: "/gh order commit first", "/gh order never suggest checks
   before push".