dsh-git-badge 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -10,6 +10,40 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-10-12
+
+### Fixed
+
+- **`revert` refuses a backup from a different upstream generation.** `apply`
+  patches whichever `SEAM_DATA_DIR` it is pointed at, so the shipped default
+  (`$DSH_HOME/git-badge-seam`) and this repo's wrapper (`seam/`) each keep their
+  own backup — and applying through one leaves the other's behind. After a DSH
+  update that stale backup holds an OLDER upstream, and `revert` used to restore
+  it blindly: a silent downgrade of the installed package. `revert` now validates
+  the backup before restoring it — the current anchors must resolve against it —
+  and refuses with a clear message, changing nothing.
+- **`status` reports what `revert` would do**, under a `revert:` line: restore,
+  no-op, or REFUSE and why. SEAM.md had documented that line from the beginning;
+  it was never implemented, so the refusal could arrive as a surprise at the one
+  moment it was least welcome.
+- **A worktree registration that cannot be written now says WHY.** The store
+  swallowed the cause, so `npx dsh-git-badge checkout <path>` reported only
+  "could not write the registration" — no path, no reason, no recovery — and the
+  next reader had to rediscover that a file sandbox or a read-only home can
+  refuse the write. It now names the target file, the real errno, and the three
+  ways out.
+
+### Added
+
+- **The chip's hover card names the linked worktrees a session is NOT
+  following.** That state used to be invisible: a registration the sandbox
+  refused left a badge describing the session's own checkout, which looks exactly
+  like a session with nothing to follow, while the agent's work sat in a tree the
+  UI never mentioned. The card now reads
+  `2 linked · none registered — npx dsh-git-badge checkout <path>`. It rides
+  `detail=1` like the rest of the card's extras, so nothing at rest pays for the
+  extra `git worktree list`.
+
 ## [0.18.0] - 2026-10-12
 
 ### Fixed

package/lib/client.js

@@ -760,6 +760,24 @@ window.__ModuleLoader__.load({
 			return name;
 		}
 
+		/**
+		 * The `worktrees` row: how many LINKED worktrees this repository has while
+		 * the badge follows none of them.
+		 *
+		 * It earns its place on one thing only — the failure it makes visible. A
+		 * registration is written outside the repository, so a file sandbox or a
+		 * read-only home can refuse it. When that happens the badge silently keeps
+		 * describing the session's own checkout, and the agent's work sits in a tree
+		 * the UI never names. That state is indistinguishable from a session with
+		 * nothing to follow, so the card is the only place it can be said. The node
+		 * half computes it under `detail=1` only, so nothing at rest pays for it.
+		 */
+		function linkedWorktreesDetail(info) {
+			const linked = info?.linkedWorktrees;
+			if (typeof linked !== "number" || linked <= 0) return void 0;
+			return linked + " linked \u00B7 none registered \u2014 npx dsh-git-badge checkout <path>";
+		}
+
 		/**
 		 * ONE commit line, shared by the branch hover and the PR token's hover so
 		 * the two cannot drift apart again: a fixed-width monospace hash cell, so
@@ -1076,6 +1094,11 @@ window.__ModuleLoader__.load({
 			// WHICH checkout the badge describes, when it is a worktree. The chip shows
 			// the branch alone, so this row is the only place the tree is named.
 			add("worktree", worktreeDetail(data));
+			// The linked-but-unregistered state — the on-screen difference between
+			// "nothing to follow" and "the registration could not be written". Rides
+			// the detail payload, so it appears once the hover has fetched, exactly
+			// like the `checkout` row below it.
+			add("worktrees", linkedWorktreesDetail(data));
 			// The conversation's OWN directory, present only when the badge is
 			// 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
@@ -1870,7 +1893,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, cleanGate, moveCategory };
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, linkedWorktreesDetail, actionToken, ghSkillActions, cleanGate, moveCategory };
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -1686,6 +1686,17 @@ function apply(ctx) {
 						}
 					}
 				}
+				if (detail && info.git === true && session !== null && effective.worktree === void 0) {
+					// No registration is in effect, so the badge describes the session's OWN
+					// checkout. When this repository also has LINKED worktrees, that is the one
+					// state worth naming: a registration write that failed (a file sandbox, a
+					// read-only home) looks exactly like a session with nothing to follow, and
+					// the agent's work then sits in a tree the badge never mentions. Gated on
+					// detail=1 (a pointer resting on the chip), so nothing at rest pays for the
+					// extra `git worktree list`.
+					const { worktrees } = await worktreesFor(target.path);
+					if (worktrees.length > 1) body.linkedWorktrees = worktrees.length - 1;
+				}
 				// Echo the resolved workspace id. SSE events identify the workspace,
 				// not the session, so a session-targeted client has no other way to
 				// tell whether an event belongs to it — without this the input chip

package/package.json

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

package/seam/apply.js

@@ -47,9 +47,9 @@
  * Usage: npx dsh-git-badge apply | revert | status | checkout <path|--clear>
  *        (equivalently apply.js <verb>; checkout delegates to checkout.js)
  */
-import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import { copyFileSync, existsSync } from "node:fs";
 import { MARKER } from "./anchors.js";
-import { backupState, doPatch, doRestore, installPaths, inspect, KNOWN_GOOD_HASH, sha256 } from "./patch.js";
+import { backupState, doPatch, doRestore, installPaths, inspect, KNOWN_GOOD_HASH, revertPlan } from "./patch.js";
 import { installSkill } from "./skill.js";
 import { writeRestartMarker } from "./store.js";
 
@@ -115,6 +115,17 @@ if (verb === "status") {
 		default:
 			console.log(`verdict:    ${r.state.toUpperCase()} — see error above.`);
 	}
+	// Whether `revert` would act or refuse, reported BEFORE anyone needs it. The
+	// refusal can be about a backup that lives in a different store than the one
+	// being inspected, so revert time is the wrong moment to learn about it.
+	const plan = revertPlan(paths);
+	const revertLine =
+		plan.action === "refuse"
+			? `would REFUSE — ${plan.reason}`
+			: plan.action === "noop"
+				? `nothing to do — ${plan.reason}`
+				: `would restore the bytes as found — ${plan.reason}`;
+	console.log(`revert:     ${revertLine}`);
 	process.exit(VERDICT_EXIT_1.has(r.state) ? 1 : 0);
 }
 
@@ -182,40 +193,48 @@ if (verb === "apply") {
 	}
 	console.log(`now install the plugin:  dsh plugin --profile web add dsh-git-badge`);
 } else {
-	// revert
-	if (existsSync(paths.backupClient)) {
-		const r = inspect(paths);
-		const installedHash = r.hash;
-		const backupHash = sha256(readFileSync(paths.backupClient, "utf8"));
-		if (installedHash === backupHash) {
-			// Idempotent re-run: the installed bytes already ARE the backup.
-			console.log("already reverted — installed client.js matches the backup; nothing to do.");
-		} else if (r.state === "ours-current" || r.state === "ours-stale" || r.state === "ours-corrupt") {
-			doRestore(paths);
-			console.log("reverted client.js/index.js to the bytes as found before patching.");
-			// A revert also changes bytes the running bundles were composed from.
-			writeRestartMarker("revert");
-		} else {
-			// Installed file is not ours => upstream replaced it since patching.
-			console.error("REFUSING to revert: the installed client.js is not this repo's");
-			console.error(`artifact (state: ${r.state}), so upstream replaced it since the patch was`);
-			console.error("applied. Restoring the backup would DOWNGRADE the package.");
-			console.error("Nothing was changed. If the downgrade is really what you want, restore");
-			console.error(`${paths.backupClient} by hand.`);
-			process.exit(1);
-		}
+	// revert — ONE decision (revertPlan), shared with the `status` report, so the
+	// refusal a user is warned about is the refusal they actually get.
+	const plan = revertPlan(paths);
+	const r = inspect(paths);
+	const ours = r.state === "ours-current" || r.state === "ours-stale" || r.state === "ours-corrupt";
+	const hasBackup = existsSync(paths.backupClient);
+
+	if (plan.action === "restore") {
+		doRestore(paths);
+		console.log("reverted client.js/index.js to the bytes as found before patching.");
+		// A revert also changes bytes the running bundles were composed from.
+		writeRestartMarker("revert");
+	} else if (plan.action === "noop") {
+		// Idempotent re-run: the installed bytes already ARE the backup.
+		console.log(`already reverted — ${plan.reason}; nothing to do.`);
+	} else if (hasBackup && ours) {
+		// The dangerous case: WE patched this build, but the backup beside it is
+		// from another upstream generation. Restoring it downgrades the package.
+		console.error("REFUSING to revert: the backup in this store is not a build this patch");
+		console.error(`targets — ${plan.reason}.`);
+		console.error("Restoring it would replace the installed build with an older upstream that the");
+		console.error("current anchors cannot re-apply. Nothing was changed.");
+		console.error("Revert from the store that patched this build instead — its `status` prints");
+		console.error("`revert:     would restore ...` — or reinstall the DSH package.");
+		process.exit(1);
+	} else if (hasBackup) {
+		// Installed file is not ours => upstream replaced it since patching.
+		console.error("REFUSING to revert: the installed client.js is not this repo's");
+		console.error(`artifact (state: ${r.state}). Restoring the backup would DOWNGRADE the`);
+		console.error("package. Nothing was changed. If the downgrade is really what you want,");
+		console.error(`restore ${paths.backupClient} by hand.`);
+		process.exit(1);
+	} else if (ours) {
+		console.error("REFUSING: the installed file is patched but no backup exists in");
+		console.error("the seam data dir, so the original bytes are unknown here. Options:");
+		console.error("  1. If you applied from a clone of the plugin's repository, run its");
+		console.error("     wrapper instead — it keeps its own backup:");
+		console.error("       <clone>/seam/apply.sh revert");
+		console.error("  2. Otherwise reinstall the package — pristine files, guaranteed:");
+		console.error("       npm i -g @deepseek-ai/dsh@latest");
+		process.exit(1);
 	} else {
-		const r = inspect(paths);
-		if (r.state === "ours-current" || r.state === "ours-stale" || r.state === "ours-corrupt") {
-			console.error("REFUSING: the installed file is patched but no backup exists in");
-			console.error("the seam data dir, so the original bytes are unknown here. Options:");
-			console.error("  1. If you applied from a clone of the plugin's repository, run its");
-			console.error("     wrapper instead — it keeps its own backup:");
-			console.error("       <clone>/seam/apply.sh revert");
-			console.error("  2. Otherwise reinstall the package — pristine files, guaranteed:");
-			console.error("       npm i -g @deepseek-ai/dsh@latest");
-			process.exit(1);
-		}
 		console.log("no backup present and nothing of ours installed; client.js left untouched.");
 	}
 	// restore the no-op host half if no backup of the original exists

package/seam/checkout.js

@@ -77,8 +77,19 @@ if (!paths.includes(path)) {
 	process.exit(1);
 }
 
-if (!writeSessionCheckout(sessionId, path)) {
-	console.error("[dsh-git-badge] could not write the registration; the badge keeps its inferred checkout.");
+const written = writeSessionCheckout(sessionId, path);
+if (written.ok !== true) {
+	// The failure the badge cannot show. Say the CAUSE and the three ways out, so
+	// this never reads as "the worktree has no changes" — which is exactly what a
+	// failed registration looks like from the UI.
+	console.error(`[dsh-git-badge] could not write the registration to ${written.file}`);
+	console.error(`  reason: ${written.error}${written.code === "" ? "" : ` (${written.code})`}`);
+	console.error("  The badge therefore keeps describing THIS session's own checkout, so the");
+	console.error("  worktree's state will not appear. Pick one:");
+	console.error("    1. give this process write access to that directory, then re-run this command;");
+	console.error("    2. run this command from a shell that already has it;");
+	console.error("    3. add the worktree as its own dsh workspace — a session opened there needs no");
+	console.error("       registration at all, because its working directory IS the worktree.");
 	process.exit(1);
 }
 console.log(`[dsh-git-badge] this session's checkout is now ${basename(path)} (${branchOf(path)}).`);

package/seam/patch.js

@@ -120,6 +120,45 @@ export function backupState(paths) {
 				: "drift";
 }
 
+/**
+ * What `revert` WOULD do, without doing it — the ONE decision the `status`
+ * report and the revert branch both read, so they cannot drift apart. They did:
+ * `revert: would REFUSE` was documented in SEAM.md and never implemented, which
+ * is the same shape of bug as the hole this closes.
+ *
+ * A legitimate backup is the bytes as found before patching, so the CURRENT
+ * anchors must still resolve against it (`backupState` is "patchable"). A store
+ * whose backup predates a DSH update satisfies neither condition: it holds an
+ * OLDER upstream, so restoring it would downgrade the package AND leave a build
+ * this patch cannot re-apply.
+ *
+ * That store is easy to acquire by accident, because `apply` patches whichever
+ * store it is pointed at: the shipped patcher defaults to
+ * `$DSH_HOME/git-badge-seam` while this repo's wrapper keeps its own under
+ * `seam/`. Apply through one and the other's backup stays behind.
+ *
+ * @returns {{ action: "restore" | "noop" | "refuse", reason: string }}
+ */
+export function revertPlan(paths) {
+	if (!existsSync(paths.backupClient))
+		return { action: "refuse", reason: "no backup in this store, so the original bytes are unknown" };
+	const r = inspect(paths);
+	if (r.hash === sha256(readText(paths.backupClient)))
+		return { action: "noop", reason: "installed client.js already matches the backup" };
+	if (r.state !== "ours-current" && r.state !== "ours-stale" && r.state !== "ours-corrupt")
+		return {
+			action: "refuse",
+			reason: `the installed client.js is not this repo's artifact (state: ${r.state})`
+		};
+	const bstate = backupState(paths);
+	if (bstate !== "patchable")
+		return {
+			action: "refuse",
+			reason: `the backup is '${bstate}' — a different upstream generation, not a build this patch targets`
+		};
+	return { action: "restore", reason: "the backup is a build this patch targets" };
+}
+
 /**
  * Backup the bytes AS FOUND, patch client.js in place, install the no-op host
  * half, and record the restart marker (`reason` names the actor: apply |

package/seam/store.js

@@ -105,20 +105,24 @@ export function readSessionCheckouts(file = sessionCheckoutsPath()) {
 /**
  * Register the checkout a session is working in. Written by the agent (the
  * git-worktree and /gh checkout paths), read by the node half.
+ *
+ * Returns the OUTCOME rather than a boolean, because the reason matters here more
+ * than anywhere else in this file. A registration that cannot be written is the
+ * one failure the badge CANNOT show: the session quietly keeps its inferred
+ * checkout, which looks identical to a session with nothing to follow. The caller
+ * gets `error`/`code` so it can say what went wrong and where, instead of
+ * reporting a bare failure that the next reader has to rediscover the hard way.
  */
 export function writeSessionCheckout(sessionId, path) {
+	const file = sessionCheckoutsPath();
 	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;
+		writeFileSync(file, JSON.stringify({ schema: "dsh-git-badge/session-checkout/v1", sessions }), "utf8");
+		return { ok: true, file };
+	} catch (error) {
+		return { ok: false, file, error: String(error?.message ?? error), code: String(error?.code ?? "") };
 	}
 }