dsh-git-badge 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Versions before 0.6.0 predate this file; their history is in `git log` and on
+npm. 0.6.0 is the first release recorded here.
+
+## [Unreleased]
+
+## [0.7.0] - 2026-09-12
+
+### Changed
+
+- **Both surfaces draw the same status mark.** The input chip no longer leads with
+  a 🔴/🟡/🟢 emoji dot: it renders the SAME 12px SVG mark as the sidebar row — a
+  filled **circle**, or a **tree** for a linked `git worktree` — so the shape says
+  *worktree or not* and the fill says *status*, identically wherever the badge
+  appears. The `⑂` worktree glyph is gone with the emoji: the tree shape already
+  says "worktree". The mark is drawn rather than typed because 🌳 is a **colour
+  emoji** — CSS cannot tint its leaves — and the fill comes from the app's own
+  `--dsw-alias-state-{success,warn,error}-primary` tokens, so the mark follows
+  light/dark and custom themes, which the hardcoded emoji could not. Neither colour
+  nor shape is the only channel: the mark carries an accessible name.
+- **The sidebar row shows status, not the branch.** The row keeps the workspace
+  name on the left and floats the status mark to the right, with a worktree's
+  directory name beside it; the `|` separator is gone. The branch, sync counts and
+  operation token stay on the input chip, the surface scoped to the current
+  conversation.
+- **The status endpoint no longer accepts a filesystem path.** The caller now says
+  *who it is* and the server resolves the workspace itself: `?session=<id>` for the
+  input chip, `?workspace=<id>` for a sidebar row. `?path=` is refused with
+  `target-required`; unresolvable ids return `session-not-found` or
+  `workspace-not-found`. The path was previously caller-chosen (allowlist-bounded
+  and read-only, but still chosen by the caller) on a route that answers without
+  GUI authentication.
+- A session is resolved through the workspace registry first, so a conversation
+  that is no longer live still renders a badge. The live session's directory is
+  consulted only for the window before a new session is attached to its workspace,
+  and the registry still validates it.
+- The client half no longer requires the `workspaces` service — declared services
+  are now just `["slots"]` — and change notifications carry the workspace id, so
+  subscribers match on identity rather than on a path.
+
+### Added
+
+- **A client-half test suite, plus submodule coverage.** `test/client.test.mjs`
+  loads the real `lib/client.js` behind a stub module loader and renders both
+  registered surfaces, so the mark's shape/colour rules, the row's "never show the
+  branch" rule, the right-float and the worktree-name suppression are asserted in
+  CI rather than eyeballed. The node half gains a real-submodule fixture: a
+  submodule is asserted **not** to be a worktree (its gitfile alone must not decide
+  it — worktree-ness is the `commondir` marker) while its out-of-tree git dir is
+  still watched, like a linked worktree's.
+- **The input chip now says which working tree a conversation is in.** A linked
+  `git worktree`'s directory name is appended after the branch —
+  `🌳 main hotfix-tree ↑0 ↓2 ✎3` — because several worktrees of one repository
+  otherwise render identical chips and the chip carries no other workspace
+  identity. The name is dropped when the branch already implies it (`repo-feat-x`
+  on `feat-x` shows just the tree), a main checkout appends nothing, and the
+  response reports `isWorktree` / `worktreeName` from one stat of the git dir the
+  existing `rev-parse` already returned — no extra git invocation. Naming the
+  worktree is chip-only, like the operation token. The value is a directory NAME,
+  never a path.
+- **A server-side poll fallback for workspaces whose file watcher failed.** A
+  workspace whose recursive `fs.watch` could not be established, or which later
+  errored, is polled every 5s on a state key (status + refs fingerprint +
+  in-progress operation) instead of depending only on the client's 60s fallback.
+- `seam/apply.sh status` — reports patched / pristine / upstream-landed / drifted
+  by hash, exit 1 on drift with the exact rebuild commands.
+
+### Fixed
+
+- **The input chip now refreshes on change events.** Change events identify the
+  *workspace*, and the client matched them against its own target id. A sidebar row
+  targets by workspace id so rows kept working, but the chip targets by session id,
+  which can never equal a workspace id — so its handler never fired and the chip
+  only updated when it remounted (switching conversations) or on the 60s fallback
+  poll. The status response now echoes the resolved workspace id and the client
+  matches on that. This was a regression in the server-side resolution change.
+- **A linked worktree's badge only refreshed on a file edit.** The watcher watched
+  the workspace root, but a linked worktree's git dir lives OUTSIDE it
+  (`<main>/.git/worktrees/<name>`), so `git add`, `git commit` and `git checkout`
+  there wrote nothing the root watch could see: the badge stayed stale until a
+  worktree file changed or the client's 60s poll fired. The per-worktree git dir
+  now gets its own watcher, resolved from the `.git` gitfile (which covers
+  submodules too), and either watcher erroring drops both and hands over to the
+  degraded poll. A regression test that stages a file written before the watch
+  existed fails without the second watcher.
+- **The TTL fetch no longer delays the status response.** `ahead`/`behind` are
+  read from the local remote-tracking ref, and the fetch that refreshes it was
+  awaited before answering, so any request arriving after the 60s TTL had lapsed
+  paid a full network fetch first (~3.3s measured) — which is the first request
+  after every TTL window, i.e. constantly while editing. Badge updates triggered
+  by an edit took seconds for a repo with a remote. The response is now served
+  from the refs at hand and the fetch runs out of band; when it succeeds it
+  notifies subscribers, which reconverge in ~40ms. Same call, expired TTL: 27ms.
+  The trade is that `ahead`/`behind` can lag by up to one fetch — branch, dirty
+  state and file counts are never delayed.
+- The plugin's `surfaces:` console line reported the boot-time race instead of the
+  outcome: it printed `sidebar rows = off (seam absent)` while row badges were
+  visibly rendering, because it sampled the seam declaration before the workspace
+  browser published it. It now reports from the registration callback, and the
+  boot-time line says it is awaiting the seam rather than declaring it missing.
+
+## [0.6.0] - 2026-09-12
+
+### Fixed
+
+- **`✎n` under-counted new files.** Git collapses a new directory into a single
+  status entry, so adding a folder of 3 files displayed `✎1`. Untracked files are
+  now counted individually. If walking a very large untracked tree exceeds the time
+  budget, the badge falls back to the collapsed count and reports which mode
+  answered (`untrackedMode`) instead of silently showing a wrong number.
+
+### Added
+
+- **An in-progress operation token.** A paused merge, rebase, cherry-pick, revert,
+  bisect or sequencer run now appears after the branch name —
+  `🟡 main ⚔rebase ↑0 ↓2 ✎3`. A rebase whose conflicts are already staged has no
+  unmerged files, so the three-state dot could not express it. The dot contract
+  itself is unchanged, and the token is chip-only.
+- **A 41-test node-half suite** (`npm test`) covering the status parser, git
+  plumbing against real repositories, request routing, SSE framing and the
+  filesystem watcher — runnable without booting DSH.
+- **A CI test workflow** running the suite on Node 20/22/24.
+
+### Changed
+
+- Publishing runs through **npm trusted publishing** (OIDC) on a published
+  release, gated on the suite, with SLSA provenance — no long-lived token.
+- Event stream hardening: `x-accel-buffering: no`, named `change` frames, cleanup
+  on disconnect, and an unload disposer that also releases the filesystem watchers.
+- `detail=1` is annotated as having no consumer yet (the hover card remains
+  pending). Its comment previously claimed `log -1` while the code ran `log -3`.
+
+[Unreleased]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/releases/tag/v0.7.0
+[0.6.0]: https://github.com/Kevin-McIsaac/dsh-workspace-git-badge/releases/tag/v0.6.0

package/README.md

@@ -2,10 +2,12 @@
 
 Git status badges for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
 
-- **Input-row chip** — `🟢 main` next to the access picker, showing the git state of the workspace the current conversation is attached to. Works on every install.
-- **Sidebar row badges** — full Claude-Code-statusline-style badges (`| 🟡 main ↑0 ↓2 ✎3`) on workspace rows. Requires the `sidebar.workspaces.row` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
+- **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.
+- **Sidebar row badges** — the same status mark floated to the right of each workspace row (`Project 1   ●`), with a linked worktree's name beside it (`Project 2   hotfix-tree 🌳`). Requires the `sidebar.workspaces.row` seam; without it the plugin degrades to chip-only and logs what's active to the browser console.
 
-Event-driven freshness: working trees are watched and updates push over SSE — badges flip within ~1s of any commit, stage, or edit. One `git status --porcelain=v2` call per sample; the API only answers registered workspace paths.
+The leading **mark** is identical on both surfaces: a circle filled with the status colour, or a **tree** when the workspace is a linked `git worktree`. (`●`/`🌳` 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. One `git status --porcelain=v2` call per sample. The status API takes **no path**: the caller passes a session id (chip) or workspace id (row) and the server resolves the directory itself.
 
 ## Install
 
@@ -17,6 +19,10 @@ Restart the web process, refresh the browser. Requires Node ≥ 20 and `git` on
 
 Seam details: [github.com/Kevin-McIsaac/dsh-workspace-git-badge](https://github.com/Kevin-McIsaac/dsh-workspace-git-badge) (SEAM.md / PR.md).
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT

package/lib/client.js

@@ -1,10 +1,16 @@
 /**
  * dsh-git-badge — client half.
  *
+ * Both surfaces show the SAME status mark — a circle, or a tree for a linked
+ * worktree, filled with the status colour — so status and worktree-ness read
+ * identically wherever they appear.
+ *
  * Surfaces:
- *  - sidebar.workspaces.row (seam): row badge — dot + branch
- *  - conversation.input.left (upstream): chip — dot + branch + in-progress
- *    operation token + sync/dirty suffix
+ *  - sidebar.workspaces.row (seam): row badge — workspace name, the status mark
+ *    floated right, and a worktree's name beside it. Deliberately shows NO
+ *    branch: the chip is the surface that names it.
+ *  - conversation.input.left (upstream): chip — status mark + branch + a
+ *    worktree's name + in-progress operation token + sync/dirty suffix
  * The hover card is intentionally untouched.
  */
 window.__ModuleLoader__.load({
@@ -24,16 +30,16 @@ window.__ModuleLoader__.load({
 		const FALLBACK_POLL_MS = 60000;
 
 		/**
-		 * Path equality for SSE notifications. The node half notifies with the
-		 * registered workspace path, while a surface may hold a variant spelling
-		 * (a trailing slash). A bare === there would silently kill that row's
-		 * freshness, so normalise the one difference we can cheaply normalise.
+		 * A request target names WHO is asking, never a filesystem path — the node
+		 * half resolves the directory itself, so a surface never needs to know
+		 * one. The chip targets its conversation (`session`); a sidebar row
+		 * targets the workspace id the seam hands it. The query string doubles as
+		 * the cache key.
 		 */
-		function samePath(a, b) {
-			if (a === b) return true;
-			if (typeof a !== "string" || typeof b !== "string") return false;
-			const trim = (value) => value.length > 1 ? value.replace(/\/+$/, "") : value;
-			return trim(a) === trim(b);
+		function targetQuery(target) {
+			if (target === void 0 || target.id === void 0) return void 0;
+			const param = target.kind === "workspace" ? "workspace" : "session";
+			return param + "=" + encodeURIComponent(target.id);
 		}
 
 		//#region SSE change feed (one EventSource per page, ref-counted)
@@ -49,19 +55,19 @@ window.__ModuleLoader__.load({
 				// NAMED frames: the node half writes `event: change`, and onmessage
 				// never fires for a named event
 				eventSource.addEventListener("change", (message) => {
-					let path;
+					let payload;
 					try {
-						path = JSON.parse(message.data).path;
+						payload = JSON.parse(message.data);
 					} catch {
 						return;
 					}
-					// invalidate every cache entry for this workspace, then refetch
-					for (const key of [...GIT_CACHE.keys()]) {
-						if (samePath(key, path)) GIT_CACHE.delete(key);
-					}
+					// The server names the workspace it watched, so a subscriber that
+					// asked by id matches without ever knowing a path. Each
+					// subscriber refetches itself, and the per-key in-flight map
+					// collapses the resulting burst into one request.
 					for (const fn of [...eventListeners]) {
 						try {
-							fn(path);
+							fn(payload);
 						} catch {
 							/* one bad subscriber must not starve the rest */
 						}
@@ -81,76 +87,122 @@ window.__ModuleLoader__.load({
 
 		/**
 		 * Shared git-status hook. Fetches once on mount and then only when the
-		 * node half's watcher reports a change for this workspace (SSE), plus a
-		 * slow safety-net poll in case the stream dies silently. Returns
-		 * undefined while loading and for non-git paths.
+		 * node half's watcher reports a change for this target (SSE), plus a slow
+		 * safety-net poll in case the stream dies silently. Returns undefined
+		 * while loading and for non-git workspaces.
 		 */
-		function useGitStatus(cwd) {
-			const cacheKey = cwd;
+		function useGitStatus(target) {
+			const cacheKey = targetQuery(target);
 			const hit = cacheKey === void 0 ? void 0 : GIT_CACHE.get(cacheKey);
-			const [info, setInfo] = react.useState(hit !== void 0 ? hit.data : void 0);
+			// state carries the key it belongs to: switching conversations changes
+			// the key, and showing the previous session's badge until the new fetch
+			// lands would be wrong
+			const [state, setState] = react.useState({ key: cacheKey, data: hit === void 0 ? void 0 : hit.data });
 			react.useEffect(() => {
-			if (cacheKey === void 0) return;
-			let alive = true;
-			const apply = (data) => {
-				// A degraded response (git timeout/failure) must never clobber a
-				// good cached badge — keep the last-known state until a real
-				// event or the fallback poll succeeds.
-				if (data !== null && data.error !== void 0 && GIT_CACHE.has(cacheKey)) return;
-				GIT_CACHE.set(cacheKey, { at: Date.now(), data });
-				if (alive) setInfo(data);
-			};
-			const load = () => {
-				// dedupe: an in-flight fetch for this key serves all callers
-				let pending = GIT_INFLIGHT.get(cacheKey);
-				if (pending === void 0) {
-					pending = fetch("/api/git-badge?path=" + encodeURIComponent(cwd))
-						.then((r) => r.json())
-						.finally(() => GIT_INFLIGHT.delete(cacheKey));
-					GIT_INFLIGHT.set(cacheKey, pending);
+				if (cacheKey === void 0) return;
+				let alive = true;
+				// The workspace this target resolved to, taken from the response (the
+				// server echoes it). THIS is what events are matched against: an event
+				// carries a workspace id, and a session-targeted chip has only a
+				// session id, so comparing the two directly never matches.
+				let resolvedWorkspace;
+				// Re-seed from cache when the key changes (switching conversations):
+				// render the last-known badge immediately instead of blanking until the
+				// fetch lands, and take the workspace id from it so events still match.
+				const cached = GIT_CACHE.get(cacheKey);
+				if (cached !== void 0) {
+					if (typeof cached.data?.workspace === "string") resolvedWorkspace = cached.data.workspace;
+					setState({ key: cacheKey, data: cached.data });
 				}
-				pending.then(apply).catch(() => {});
-			};
-			load();
-			// this workspace's watcher events → refetch
-			const unsubscribe = subscribeGitEvents((path) => {
-				if (samePath(path, cwd)) load();
-			});
-			const fallback = setInterval(load, FALLBACK_POLL_MS);
-			return () => {
-				alive = false;
-				unsubscribe();
-				clearInterval(fallback);
-			};
-		}, [cacheKey]);
-			return info;
+				const apply = (data) => {
+					// A degraded response (git timeout/failure) must never clobber a
+					// good cached badge — keep the last-known state until a real
+					// event or the fallback poll succeeds.
+					if (data !== null && data.error !== void 0 && GIT_CACHE.has(cacheKey)) return;
+					if (data !== null && typeof data.workspace === "string") resolvedWorkspace = data.workspace;
+					GIT_CACHE.set(cacheKey, { at: Date.now(), data });
+					if (alive) setState({ key: cacheKey, data });
+				};
+				const load = () => {
+					// dedupe: an in-flight fetch for this key serves all callers
+					let pending = GIT_INFLIGHT.get(cacheKey);
+					if (pending === void 0) {
+						pending = fetch("/api/git-badge?" + cacheKey)
+							.then((r) => r.json())
+							.finally(() => GIT_INFLIGHT.delete(cacheKey));
+						GIT_INFLIGHT.set(cacheKey, pending);
+					}
+					pending.then(apply).catch(() => {});
+				};
+				load();
+				const unsubscribe = subscribeGitEvents((payload) => {
+					// An event with no workspace id (no watcher record for that path)
+					// cannot be attributed, and neither can one arriving before we have
+					// resolved our own target — refetch rather than guess, since a
+					// missed refresh is the bug this guards and an extra request is cheap
+					// (the in-flight map collapses bursts).
+					if (payload.workspace === void 0 || resolvedWorkspace === void 0 || payload.workspace === resolvedWorkspace) load();
+				});
+				const fallback = setInterval(load, FALLBACK_POLL_MS);
+				return () => {
+					alive = false;
+					unsubscribe();
+					clearInterval(fallback);
+				};
+			}, [cacheKey]);
+			return state.key === cacheKey ? state.data : void 0;
 		}
 
 		/**
-		 * Three-state dot color, shared by the sidebar row badge and the
-		 * composer chip. Checked top-down, first match wins:
-		 *  - RED: unmerged files (mid-conflict, git is blocked) — or a dirty
+		 * Three-state status, checked top-down, first match wins:
+		 *  - "error": unmerged files (mid-conflict, git is blocked) — or a dirty
 		 *    tree that is ALSO behind upstream (unsaved edits on an outdated
 		 *    base: commit-then-pull friction ahead).
-		 *  - YELLOW: dirty files, or any ahead/behind (routine work or sync
+		 *  - "warn": dirty files, or any ahead/behind (routine work or sync
 		 *    pending — including the previously "quiet" green-but-↓1 case).
-		 *  - GREEN: clean and in sync.
+		 *  - "ok": clean and in sync.
 		 * Red never means merely "behind": a clean tree one commit behind is
 		 * normal between pulls, not an alarm.
+		 *
+		 * The single source of truth for that summary. BOTH surfaces render it the
+		 * same way (see StatusMark): a circle, or a tree in a linked worktree,
+		 * filled with the colour below.
 		 */
-		function badgeDot(info) {
+		function badgeStatus(info) {
 			const dirty = info.dirty === true;
 			const behind = (info.behind || 0) > 0;
 			const ahead = (info.ahead || 0) > 0;
 			const conflict = (info.unmergedFiles || 0) > 0;
-			if (conflict || (dirty && behind)) return "\uD83D\uDD34";
-			if (dirty || ahead || behind) return "\uD83D\uDFE1";
-			return "\uD83D\uDFE2";
+			if (conflict || (dirty && behind)) return "error";
+			if (dirty || ahead || behind) return "warn";
+			return "ok";
 		}
 
 		/**
-		 * Sync/dirty suffix — INPUT CHIP ONLY. The sidebar row badge shows
-		 * status + branch alone; the chip is the detailed surface. Rule set:
+		 * Mark fill per status, from the app's own semantic tokens so BOTH surfaces
+		 * follow light/dark and custom themes — which a hardcoded emoji cannot do.
+		 * The literals are only fallbacks for use outside DSH.
+		 */
+		const MARK_FILL = {
+			error: "var(--dsw-alias-state-error-primary, #e5484d)",
+			warn: "var(--dsw-alias-state-warn-primary, #d29922)",
+			ok: "var(--dsw-alias-state-success-primary, #30a46c)"
+		};
+
+		/**
+		 * Accessible name per status, WITHOUT the "git" prefix — the mark adds
+		 * "git: " or "git worktree: ", so shape and colour are never the only
+		 * channel for either fact.
+		 */
+		const STATUS_LABEL = {
+			error: "conflict, or uncommitted changes on an outdated base",
+			warn: "uncommitted changes, or out of sync with upstream",
+			ok: "clean and in sync"
+		};
+
+		/**
+		 * Sync/dirty suffix — INPUT CHIP ONLY. The sidebar row shows status alone;
+		 * the chip is the surface that carries the numbers. Rule set:
 		 *  - dirty files render as ✎n (pencil = worktree files, distinct from
 		 *    the ↑/↓ commit-sync axis)
 		 *  - while dirty, BOTH sync counts render including zeros (↑0 ↓2 ✎3),
@@ -171,9 +223,9 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * In-progress operation token — INPUT CHIP ONLY (the row badge stays
-		 * dot + branch). A paused rebase or cherry-pick whose conflicts are all
-		 * already staged has no unmerged files, so the three-state dot cannot
+		 * In-progress operation token — INPUT CHIP ONLY (the row shows the status
+		 * tree alone). A paused rebase or cherry-pick whose conflicts are all
+		 * already staged has no unmerged files, so the three-state summary cannot
 		 * distinguish it from ordinary dirty work; this says which
 		 * history-rewriting operation git is waiting on.
 		 */
@@ -193,6 +245,45 @@ window.__ModuleLoader__.load({
 			return label === void 0 ? "" : " " + label;
 		}
 
+		/**
+		 * Linked-worktree NAME token — INPUT CHIP ONLY, and only the name: worktree-
+		 * ness itself is carried by the status mark's shape (a tree instead of a
+		 * circle) on both surfaces. The chip has no other workspace identity, so
+		 * several worktrees of one repository would otherwise render identical chips
+		 * with no way to tell which checkout a conversation is in. The node half
+		 * reports whether this is a linked worktree plus its directory NAME (never a
+		 * path).
+		 *
+		 * The name is appended only when it says something the branch does not: the
+		 * usual `repo-feat-x` directory sitting on branch `feat-x` would otherwise
+		 * read as stutter. (The ROW needs no such rule — it shows the name instead
+		 * of the branch, so there is nothing to stutter against.)
+		 */
+
+		/**
+		 * True when the worktree name is already implied by the branch name, so
+		 * showing both is pure repetition. Compared on a normalized form —
+		 * case-folded, with `/` and `_` folded to `-` — because directory and
+		 * branch conventions differ without changing the meaning (`feat/x` in a
+		 * `repo-feat-x` directory).
+		 */
+		function worktreeNameIsRedundant(name, branch) {
+			if (typeof name !== "string" || name === "" || typeof branch !== "string") return true;
+			const normalize = (value) => value.toLowerCase().replace(/[/_]/g, "-");
+			const normalizedName = normalize(name);
+			const normalizedBranch = normalize(branch);
+			return normalizedName === normalizedBranch
+				|| normalizedName.endsWith("-" + normalizedBranch)
+				|| normalizedBranch.endsWith("-" + normalizedName);
+		}
+
+		/** ` name` for a worktree whose name the branch does not already say, else "". */
+		function formatWorktreeToken(info) {
+			if (info.isWorktree !== true) return "";
+			const name = typeof info.worktreeName === "string" ? info.worktreeName : "";
+			return worktreeNameIsRedundant(name, info.branch) ? "" : " " + name;
+		}
+
 		const META_STYLE = {
 			color: "var(--dsw-alias-label-tertiary, #9ea7ad)",
 			fontSize: "12px",
@@ -202,70 +293,122 @@ window.__ModuleLoader__.load({
 		};
 
 		/**
-		 * Row badge — three-state dot + branch (sync/dirty detail lives on
-		 * the input chip):
-		 *   the_paragliding_app  | 🟢 main
-		 * Dot color via badgeDot(): green clean+synced, yellow dirty or
-		 * out-of-sync, red conflict or dirty-and-behind.
-		 * Always renders the workspace name (so the row keeps its identity);
-		 * appends the muted `| emoji branch` part only for git workspaces.
+		 * Status mark, SHARED BY BOTH SURFACES: the same 12px shape in the same fill
+		 * wherever it appears, so the sidebar row and the input chip read
+		 * identically. The FILL is the status colour; the SHAPE carries
+		 * worktree-ness — a circle for a main checkout, a tree for a linked
+		 * worktree — so the two facts never compete for the same channel.
+		 *
+		 * Drawn rather than typed because 🌳 is a COLOUR EMOJI: CSS cannot tint
+		 * its leaves, and a mark that carries the status has to be paintable.
+		 * Three overlapping crown lobes plus a trunk stay legible at this size.
+		 *
+		 * Neither colour nor shape is the only channel: the accessible name
+		 * states both.
 		 */
-		function WorkspaceGitBadge({ label, cwd }) {
-			// no detail=1: the row renders dot + branch only, and the extra log /
-			// stash calls have no consumer yet
-			const info = useGitStatus(cwd);
-			const children = [react_jsx_runtime.jsx("span", { style: { minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }, children: label })];
-			if (cwd !== void 0 && info !== void 0 && info.git === true) {
-				children.push(
-					react_jsx_runtime.jsx("span", { style: { ...META_STYLE, margin: "0 7px" }, children: "|" }),
-					react_jsx_runtime.jsx("span", { style: { ...META_STYLE, marginRight: "4px" }, children: badgeDot(info) }),
-					react_jsx_runtime.jsx("span", { style: META_STYLE, children: info.branch })
-				);
+		function StatusMark({ info }) {
+			const status = badgeStatus(info);
+			const fill = MARK_FILL[status];
+			const isWorktree = info.isWorktree === true;
+			const svg = {
+				// 14px, NOT 12px: a colour emoji draws well above its nominal size — the
+				// 🔴/🟡/🟢 dot this replaces put down ~13-14px of ink at the surfaces'
+				// 12px font-size, so a 12px box read as a shrunken dot.
+				width: 14,
+				height: 14,
+				viewBox: "0 0 12 12",
+				role: "img",
+				"aria-label": (isWorktree ? "git worktree: " : "git: ") + STATUS_LABEL[status],
+				focusable: "false",
+				style: { flex: "none", display: "block", color: META_STYLE.color }
+			};
+			if (!isWorktree) {
+				// a plain filled disc: this is a main checkout. It fills its box so the
+				// ink lands at the size the emoji dot used to.
+				return react_jsx_runtime.jsx("svg", { ...svg, children: react_jsx_runtime.jsx("circle", { cx: 6, cy: 6, r: 5.5, fill }) });
 			}
-			return react_jsx_runtime.jsx("span", { style: { display: "flex", alignItems: "center", minWidth: 0 }, children });
+			return react_jsx_runtime.jsxs("svg", {
+				...svg,
+				children: [
+					// trunk first, so the crown's lobes overlap and join it. These are the
+					// 12px-era coordinates scaled 1.15 about the tree's centre, so its ink
+					// stays comparable to the disc's instead of reading small beside it.
+					react_jsx_runtime.jsx("rect", { key: "trunk", x: 5.25, y: 7.3, width: 1.5, height: 4.14, rx: 0.63, fill: "currentColor" }),
+					react_jsx_runtime.jsx("circle", { key: "crown-1", cx: 6, cy: 3.62, r: 3.57, fill }),
+					react_jsx_runtime.jsx("circle", { key: "crown-2", cx: 3.24, cy: 5.46, r: 2.53, fill }),
+					react_jsx_runtime.jsx("circle", { key: "crown-3", cx: 8.76, cy: 5.46, r: 2.53, fill })
+				]
+			});
 		}
 
-		//#region composer chip (fallback + companion surface: conversation.composer.dock)
-		/** Client root ctx, captured at apply() for the chip's service lookups. */
-		let clientCtx = null;
+		/**
+		 * A linked worktree's directory name, or null when there is nothing to
+		 * show. A main checkout shows NO text: the row surveys status and identity,
+		 * and the branch lives on the input chip — which is why the branch is never
+		 * rendered here. The name is the one thing the row's own label (the
+		 * worktree directory by default) cannot be trusted to say once a workspace
+		 * has been renamed.
+		 */
+		function rowName(info) {
+			if (info.isWorktree !== true) return null;
+			const name = typeof info.worktreeName === "string" ? info.worktreeName : "";
+			return name === "" ? null : name;
+		}
 
 		/**
-		 * Resolve the workspace cwd attached to a session: projects the
-		 * workspaces service's snapshot store (items carry path + sessionIds)
-		 * and re-resolves on change. Returns undefined while unknown.
+		 * Row badge — workspace name on the left, the status mark floated right:
+		 *   the_paragliding_app                       ●
+		 *   worktree_thing                  hotfix-tree 🌳
+		 * Fill colour via badgeStatus(): green clean+synced, amber dirty or
+		 * out-of-sync, red conflict or dirty-and-behind. Shape via the node half's
+		 * isWorktree: circle = main checkout, tree = linked worktree.
+		 * Always renders the workspace name (so the row keeps its identity) and
+		 * appends the right-hand mark only for git workspaces. No branch, and no
+		 * `|` separator.
+		 *
+		 * Targets the row's `workspaceId`. The seam also passes `cwd`, which is
+		 * deliberately ignored: the node half resolves the directory itself, so
+		 * the client never has to name one. A row with no workspaceId (the
+		 * ungrouped bucket) has no workspace to report on, so it renders
+		 * name-only.
 		 */
-		function useSessionWorkspaceCwd(sessionId) {
-			const workspaces = clientCtx === null ? null : clientCtx.get("workspaces");
-			const resolve = () => {
-				if (sessionId === void 0 || workspaces === void 0) return void 0;
-				const item = workspaces.list.getSnapshot().items.find((w) => w.sessionIds !== void 0 && w.sessionIds.includes(sessionId));
-				return item === void 0 ? void 0 : item.path;
-			};
-			const [cwd, setCwd] = react.useState(resolve);
-			react.useEffect(() => {
-				if (sessionId === void 0 || workspaces === void 0) return;
-				setCwd(resolve());
-				return workspaces.list.subscribe(() => {
-					setCwd(resolve());
-				});
-			}, [sessionId, workspaces]);
-			return cwd;
+		function WorkspaceGitBadge({ label, workspaceId }) {
+			// no detail=1: the row needs status and identity only, and the extra
+			// log / stash calls have no consumer yet
+			const info = useGitStatus(workspaceId === void 0 ? void 0 : { kind: "workspace", id: workspaceId });
+			const children = [react_jsx_runtime.jsx("span", { style: { minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }, children: label })];
+			if (workspaceId !== void 0 && info !== void 0 && info.git === true) {
+				// marginLeft:auto floats the mark to the right edge, so the status
+				// shape holds a fixed right-hand column and a worktree's name grows
+				// leftwards from it instead of shoving the shape around.
+				const meta = [];
+				const name = rowName(info);
+				if (name !== null) meta.push(react_jsx_runtime.jsx("span", { key: "name", style: META_STYLE, children: name }));
+				meta.push(react_jsx_runtime.jsx(StatusMark, { key: "mark", info }));
+				children.push(react_jsx_runtime.jsx("span", { style: { display: "inline-flex", alignItems: "center", gap: "6px", flex: "none", marginLeft: "auto", paddingLeft: "8px" }, children: meta }));
+			}
+			return react_jsx_runtime.jsx("span", { style: { display: "flex", alignItems: "center", minWidth: 0, width: "100%" }, children });
 		}
 
+		//#region composer chip (upstream additive surface: conversation.input.left)
 		/**
-		 * Chip line docked at the composer: git state of the workspace the
-		 * CURRENT conversation is attached to. Works on unpatched installs
-		 * (conversation.composer.dock is an upstream additive slot), and stays
-		 * useful next to the sidebar rows on patched/upstream-seam installs
-		 * because it is context-anchored ("where am I") rather than surveying.
+		 * Chip line in the input row: git state of the workspace the CURRENT
+		 * conversation is attached to. It targets the session id and lets the node
+		 * half resolve the workspace, so this surface needs no `workspaces`
+		 * service, no cwd and no path plumbing at all. Works on unpatched installs
+		 * (conversation.input.left is an upstream additive slot), and stays useful
+		 * next to the sidebar rows because it is context-anchored ("where am I")
+		 * rather than surveying.
 		 */
 		function ComposerGitChip({ sessionId }) {
-			const cwd = useSessionWorkspaceCwd(sessionId);
-			// no detail=1 either: nothing renders lastCommits / stashCount yet, and
-			// asking for them would add a log -3 plus a stash list to every refresh
-			const info = useGitStatus(cwd);
-			if (cwd === void 0 || info === void 0 || info.git !== true) return null;
-			const text = badgeDot(info) + " " + info.branch + formatOperationToken(info) + formatGitSuffix(info);
+			// no detail=1: nothing renders lastCommits / stashCount yet, and asking
+			// for them would add a log -3 plus a stash list to every refresh
+			const info = useGitStatus(sessionId === void 0 ? void 0 : { kind: "session", id: sessionId });
+			if (info === void 0 || info.git !== true) return null;
+			// the mark is an element now rather than a leading glyph in the string, so
+			// the SAME StatusMark the sidebar row draws carries the status here too;
+			// the container's 4px gap supplies the space the emoji's own did
+			const text = info.branch + formatWorktreeToken(info) + formatOperationToken(info) + formatGitSuffix(info);
 			return react_jsx_runtime.jsx("span", {
 				style: {
 					display: "inline-flex",
@@ -278,28 +421,46 @@ window.__ModuleLoader__.load({
 					whiteSpace: "nowrap",
 					cursor: "default"
 				},
-				children: text
+				children: [
+					react_jsx_runtime.jsx(StatusMark, { key: "mark", info }),
+					react_jsx_runtime.jsx("span", { key: "text", children: text })
+				]
 			});
 		}
 		//#endregion
 
-		const inject = ["slots", "workspaces"];
+		// `workspaces` is no longer required: both surfaces target an id and the
+		// node half resolves the workspace, so the client never needs a service
+		// lookup. Fewer declared services also means fewer ways to fail to load.
+		const inject = ["slots"];
 
 		/**
 		 * Register the badge into both seams. The seam owner hands each entry the
-		 * row owner share as props; the badge destructures { workspaceId, cwd,
-		 * label } from it.
+		 * row owner share as props; the badge destructures { workspaceId, label }
+		 * and deliberately ignores the cwd it is also given.
 		 */
 		function apply(ctx) {
-			clientCtx = ctx;
 			// 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 row seams never get declared, so those two
-			// registrations simply never render anything.
-			ctx.slots.inject("sidebar.workspaces.row", () => ctx.slots.register({
-				name: "sidebar.workspaces.row",
-				id: "git-badge"
-			}, WorkspaceGitBadge));
+			// unpatched install the row seam is never declared, so this callback
+			// never fires and the row badge simply never renders.
+			//
+			// The registration is reported from INSIDE the callback on purpose: a
+			// `spec()` check here at apply() time runs before the workspace browser
+			// declares the seam, so it reports the boot race rather than the
+			// outcome. That mistake made the old one-shot line claim "sidebar rows
+			// = off" while five row badges were rendering.
+			let rowsReported = false;
+			ctx.slots.inject("sidebar.workspaces.row", () => {
+				if (!rowsReported) {
+					rowsReported = true;
+					console.info("[dsh-git-badge] surfaces: sidebar rows = on (seam present).");
+				}
+				return ctx.slots.register({
+					name: "sidebar.workspaces.row",
+					id: "git-badge"
+				}, WorkspaceGitBadge);
+			});
 			// Input-row chip: upstream additive slot rendered in the input bar's
 			// leading cluster, right after the access picker — the git state sits
 			// with the controls that govern the conversation. Present on every
@@ -312,7 +473,7 @@ window.__ModuleLoader__.load({
 				inject: (sessionId) => ({ sessionId })
 			}, ComposerGitChip));
 			const seamDeclared = ctx.slots.spec("sidebar.workspaces.row") !== void 0;
-			console.info("[dsh-git-badge] surfaces: input chip = on; sidebar rows = " + (seamDeclared ? "on (seam present)" : "off (seam absent — sidebar badges need the sidebar.workspaces.row seam)") + ".");
+			console.info("[dsh-git-badge] surfaces: input chip = on; sidebar rows = " + (seamDeclared ? "on (seam present)." : "awaiting the sidebar.workspaces.row seam — the line above reports it if it appears."));
 		}
 
 		exports.apply = apply;

package/lib/index.js

@@ -3,10 +3,16 @@
  *
  * Hardened git-status service behind two routes:
  *
- *   GET /api/git-badge?path=<workspace path>[&detail=1]
- *     - path allowlist: only directories registered as DSH workspaces
- *       (WorkspaceRegistry records) are ever queried — no filesystem probing
- *       of arbitrary paths.
+ *   GET /api/git-badge?workspace=<workspaceId>   (sidebar rows)
+ *   GET /api/git-badge?session=<sessionId>       (the input chip)
+ *     - NO client-supplied path is accepted. The caller names a workspace id or
+ *       a session id; the server resolves the directory itself. `?path=` was
+ *       removed precisely so a caller cannot aim the route at a directory of
+ *       its choosing, even one inside the registry.
+ *     - the route is intentionally unauthenticated (it is a local, read-only
+ *       status feed), so resolution must never assume the caller is honest.
+ *       Workspace ids are generated uuids and session ids are opaque, so the
+ *       surface no longer offers anything to enumerate.
  *     - one git invocation per sample: `git --no-optional-locks status
  *       --porcelain=v2 --branch --untracked-files=all` yields branch,
  *       ahead/behind, and the changed / untracked counts in a single call
@@ -22,11 +28,22 @@
  *       markers (`MERGE_HEAD`, `rebase-merge`, …) are stat'd — surfaced as
  *       `operation`, so a paused rebase/cherry-pick is distinguishable from
  *       ordinary dirty work even when its conflicts are already staged.
- *     - ahead/behind compare against the LOCAL remote-tracking ref, which
- *       only moves on fetch — so a TTL-bounded background fetch (60s per
- *       toplevel) runs before status when the ref can be stale. `GIT_TERMINAL_PROMPT=0`
- *       and the shared timeout keep an offline/slow remote from stalling the
- *       route; on fetch failure the stale-ref answer is served as-is.
+ *     - the same invocation identifies a LINKED WORKTREE: its git dir is
+ *       `<main>/.git/worktrees/<name>` instead of `<root>/.git`, and unlike the
+ *       main worktree's it carries a `commondir` file. One stat of the git dir
+ *       the call already returned yields `isWorktree`, plus the checkout's own
+ *       directory name as `worktreeName` — so the chip can say WHICH working
+ *       tree a conversation is in. Without it, several worktrees of one
+ *       repository render identical `🟡 main` badges. The name is a NAME, never
+ *       a path: the route takes no path and the client still needs to know none.
+ *     - ahead/behind compare against the LOCAL remote-tracking ref, which only
+ *       moves on fetch. A TTL-bounded fetch (60s per toplevel) keeps that ref
+ *       fresh, but it runs OUT OF BAND: the answer is served from the refs at
+ *       hand and a successful fetch notifies subscribers so the next refresh
+ *       carries corrected ahead/behind. Awaiting it here cost ~3.3s per request
+ *       on the first refresh after each TTL window. `GIT_TERMINAL_PROMPT=0`, the
+ *       shared timeout and the TTL bound keep an offline or slow remote harmless;
+ *       on failure the stale-ref answer simply stands.
  *     - `detail=1` adds one `log -3` plus a stash count. NOTE: no surface
  *       consumes this yet (see the annotation on gitStatus) — it is kept for
  *       the planned hover card, and never paid for by row refresh.
@@ -34,18 +51,19 @@
  *   GET /api/git-badge/events   (text/event-stream)
  *     - pushes `{ path }` dirty notifications the moment a workspace's git
  *       state can have changed. Freshness is EVENT-DRIVEN: each registered
- *       workspace root is watched recursively (.git included), so a commit /
- *       checkout / stage / worktree edit pushes one SSE message and every
- *       mounted row refetches immediately. There is no fixed polling
- *       interval anywhere in the pipeline.
+ *       workspace is watched recursively, so a commit / checkout / stage /
+ *       worktree edit pushes one SSE message and every mounted row refetches
+ *       immediately. There is no fixed polling interval anywhere in the
+ *       pipeline. A MAIN worktree's git dir is `<root>/.git` and so is covered
+ *       by the root watch; a LINKED worktree's is not, so its git dir gets a
+ *       second watcher (see the watcher region).
  *
  * When upstream lands a workspace-metadata service, this half is deleted and
  * the client half re-points at it — the seam contract does not change.
  */
 import { execFile } from "node:child_process";
-import { realpath } from "node:fs/promises";
-import { watch, existsSync } from "node:fs";
-import { join } from "node:path";
+import { watch, existsSync, readFileSync } from "node:fs";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 const inject = ["webServer", "workspaceRegistry"];
 const name = "dsh-git-badge";
@@ -68,6 +86,12 @@ const config = {
 	debounceMs: 200,
 	/** backoff before re-attempting a failed watcher (or a missing .git) */
 	watchRetryMs: 60000,
+	/**
+	 * Degraded-mode poll interval for a workspace whose watcher failed. Only used
+	 * where a real watcher could not be established or later errored — a healthy
+	 * workspace is event-driven and never polls.
+	 */
+	pollFallbackMs: 5000,
 	/** SSE comment heartbeat interval */
 	heartbeatMs: 25000,
 	/**
@@ -230,6 +254,11 @@ function operationMarker(gitDir) {
  * branch, dirty state, and ahead/behind counts (what git itself considers
  * dirty), not the subdirectory in isolation. Intentional.
  *
+ * Worktree identity is reported, not assumed: `isWorktree` marks a linked
+ * worktree and `worktreeName` names the checkout. A subdirectory of a linked
+ * worktree reports that worktree (the toplevel walk starts above it), which is
+ * the same whole-repository rule as above.
+ *
  * `wantDetail` has no consumer yet: both surfaces fetch without `detail=1`.
  * The branch is retained for the planned hover card — nothing renders
  * lastCommits / stashCount today.
@@ -248,6 +277,11 @@ async function gitStatus(dir, wantDetail) {
 	const toplevel = (topLines[0] ?? "").trim();
 	if (toplevel === "") return { git: false };
 	const gitDir = (topLines[1] ?? "").trim();
+	// A linked worktree's git dir carries a `commondir` file pointing back at
+	// the shared git dir; a main worktree's does not. Stat'ing it costs nothing
+	// extra — `gitDir` came from the invocation above. A submodule also has an
+	// out-of-tree git dir but no `commondir`, so it is correctly NOT a worktree.
+	const isWorktree = existsSync(join(gitDir, "commondir"));
 	// -uall counts untracked FILES; git's default collapses a new directory into
 	// a single entry, which is why `✎n` under-reported anyone who added a folder.
 	// Routed through config.gitRunner so the suite can force the timeout branch.
@@ -269,18 +303,26 @@ async function gitStatus(dir, wantDetail) {
 		statusOut = await sample(false);
 	}
 	if (statusOut.stdout === null) return GIT_DEGRADED;
-	let parsed = parseStatusV2(statusOut.stdout);
-	// The upstream header is the cheap gate: no upstream configured → the
-	// fetch would be a no-op probe, skip it entirely. When it fires and the
-	// fetch succeeds, re-sample so this very response already carries the
-	// fresh ahead/behind instead of lagging one cycle behind.
+	const parsed = parseStatusV2(statusOut.stdout);
+	// The upstream header is the cheap gate: with no upstream the fetch would be a
+	// no-op probe, so skip it. With one, refresh the remote-tracking refs OUT OF
+	// BAND rather than before the answer.
+	//
+	// Blocking here cost ~3.3s per request (measured: `git fetch` over SSH) on every
+	// request whose TTL had lapsed — and that is the first refresh after each 60s
+	// window, i.e. constantly while someone is editing, which made an edit-triggered
+	// badge update take seconds. So: answer now from the refs we already have, and
+	// when the background fetch succeeds, notify subscribers — the client refetches,
+	// finds the TTL fresh, and picks up the corrected ahead/behind in ~50ms. The
+	// cost of the trade is that ahead/behind can lag by up to one fetch.
 	if (parsed.upstream !== void 0) {
-		const fetched = await maybeFetch(toplevel);
-		if (fetched) {
-			statusOut = await sample(untrackedMode === "all");
-			if (statusOut.stdout === null) return GIT_DEGRADED;
-			parsed = parseStatusV2(statusOut.stdout);
-		}
+		void maybeFetch(toplevel)
+			.then((fetched) => {
+				if (fetched) notifyChange(toplevel);
+			})
+			.catch(() => {
+				/* a failed fetch just means the stale-ref answer stands */
+			});
 	}
 	const dirtyFiles = parsed.staged + parsed.unstaged + parsed.unmerged + parsed.untracked;
 	const info = {
@@ -295,6 +337,10 @@ async function gitStatus(dir, wantDetail) {
 		untrackedFiles: parsed.untracked,
 		untrackedMode,
 		operation: operationMarker(gitDir),
+		isWorktree,
+		// the checkout's own directory name (of the worktree root, so a
+		// subdirectory workspace still names the checkout it belongs to)
+		worktreeName: basename(toplevel),
 		ahead: parsed.ahead,
 		behind: parsed.behind
 	};
@@ -319,10 +365,11 @@ async function gitStatus(dir, wantDetail) {
 
 //#region git-state watcher
 /**
- * One recursive watcher per workspace `.git` directory. Any event under it
- * (HEAD swap, index write, ref update) marks the workspace dirty; a 200ms
- * debounce collapses burst events (a single `git commit` touches index,
- * refs, COMMIT_EDITMSG, objects…) into one notification.
+ * One recursive watcher per workspace, plus a second one when the git dir lives
+ * outside the workspace (a linked worktree). Any event under either (HEAD swap,
+ * index write, ref update, worktree save) marks the workspace dirty; a 200ms
+ * debounce collapses burst events (a single `git commit` touches index, refs,
+ * COMMIT_EDITMSG, objects…) into one notification.
  */
 const watchers = new Map();
 const changeListeners = new Set();
@@ -330,9 +377,12 @@ const changeListeners = new Set();
 const openStreams = new Set();
 
 function notifyChange(key) {
+	// `workspace` lets a client that asked by id match the event without ever
+	// knowing a filesystem path; `path` stays for debugging and other consumers.
+	const payload = { path: key, workspace: watchers.get(key)?.workspaceId };
 	for (const fn of changeListeners) {
 		try {
-			fn(key);
+			fn(payload);
 		} catch {
 			/* a dead SSE subscriber must never break the others */
 		}
@@ -355,45 +405,194 @@ function closeStream(stream) {
 	}
 }
 
+/**
+ * Close every watcher attached to a record, leaving the record itself in place
+ * — the retry backoff and the degraded poll live on it. Tolerates a record
+ * whose watchers were never established, so every record shape is safe.
+ */
+function closeWatchers(record) {
+	for (const watcher of [record.watcher, record.extra]) {
+		if (watcher === null || watcher === void 0) continue;
+		try {
+			watcher.close();
+		} catch {
+			/* already closed */
+		}
+	}
+	record.watcher = null;
+	if ("extra" in record) record.extra = null;
+}
+
 function unwatchWorkspace(key) {
 	const record = watchers.get(key);
 	if (record === void 0) return;
 	watchers.delete(key);
-	if (record.watcher !== null) record.watcher.close();
+	closeWatchers(record);
 	if (record.timer !== void 0) clearTimeout(record.timer);
+	if (record.poll !== void 0) clearInterval(record.poll);
+}
+
+/**
+ * Change-detection key for a workspace whose watcher failed. Deliberately cheap:
+ * it runs every `config.pollFallbackMs`, so the `-uall` walk is off the table.
+ * `status` covers worktree + index, the refs fingerprint covers what a fetch or
+ * an external checkout moves, and the marker stat covers an in-progress
+ * operation (which porcelain status does not report).
+ *
+ * The price of the cheap status: a new file inside an ALREADY untracked
+ * directory does not change the key, so on a broken-watcher workspace that case
+ * waits for the client's 60s poll. Recorded in TESTING.md rather than papered
+ * over with a `-uall` walk every few seconds. The git dir is resolved once and
+ * cached on the record.
+ *
+ * Resolves null when git could not run this tick; the caller keeps the previous
+ * key and tries again.
+ */
+async function fallbackStateKey(root, record) {
+	const status = await runGit(root, [
+		"--no-optional-locks",
+		"status",
+		"--porcelain=v2",
+		"--branch",
+		"--untracked-files=normal"
+	]);
+	if (status.stdout === null) return null;
+	if (record.gitDir === void 0) {
+		const dir = await runGit(root, ["rev-parse", "--absolute-git-dir"]);
+		record.gitDir = dir.stdout === null ? "" : dir.stdout.trim();
+	}
+	const refs = await runGit(root, ["for-each-ref", "--format=%(refname)%(objectname)", "refs/heads", "refs/remotes"]);
+	return [status.stdout, refs.stdout ?? "", operationMarker(record.gitDir) ?? ""].join("\u0000");
+}
+
+/**
+ * Start the degraded-mode poll for a workspace whose watcher could not be
+ * established, or later errored. Only ever called for a workspace that HAS a
+ * .git — a directory without one is not a repository, so polling it would be
+ * waste; the retry backoff keeps re-checking that case instead.
+ *
+ * The interval is unref'd so a forgotten one can never hold the process open
+ * (test runs included); `unwatchWorkspace` clears it properly.
+ */
+function startFallbackPoll(key, root) {
+	const record = watchers.get(key);
+	if (record === void 0 || record.poll !== void 0) return;
+	const tick = () => {
+		void (async () => {
+			const current = watchers.get(key);
+			if (current === void 0) return;
+			const next = await fallbackStateKey(root, current).catch(() => null);
+			if (next === null) return;
+			// the first tick only sets a baseline: a fresh subscriber fetches on
+			// mount, so there is nothing to announce yet
+			if (current.pollKey !== void 0 && current.pollKey !== next) notifyChange(key);
+			current.pollKey = next;
+		})();
+	};
+	record.poll = setInterval(tick, config.pollFallbackMs);
+	if (typeof record.poll.unref === "function") record.poll.unref();
+	// Baseline immediately rather than one interval from now, so a change landing
+	// right after the watcher died is still noticed on the following tick instead
+	// of being baked into the baseline and never announced.
+	tick();
+}
+
+/**
+ * The out-of-tree git dir for a workspace whose `.git` is a FILE rather than a
+ * directory — a linked worktree (`<main>/.git/worktrees/<name>`) or a submodule
+ * (`<parent>/.git/modules/<name>`). Git writes the index, HEAD and reflogs
+ * THERE, so a watcher on the worktree root alone never sees a stage, commit or
+ * checkout in a linked worktree; it only ever catches file edits. (Symptom
+ * before this fix: a worktree's badge moved only on a save or the client's 60s
+ * poll, never on commit.) Reading the gitfile mirrors git's own resolution,
+ * costs one small read at watch setup rather than another `rev-parse`, and stays
+ * correct for submodules. Returns null for a main worktree, whose `.git` is a
+ * directory already covered by the root watch.
+ */
+function outerGitDir(root) {
+	let content;
+	try {
+		// Reading the DIRECTORY `.git` of a main worktree raises EISDIR, which is
+		// the "no out-of-tree git dir" answer; a `.git` symlink to a gitfile
+		// still reads, where an isFile() stat would have followed it instead.
+		content = readFileSync(join(root, ".git"), "utf8");
+	} catch {
+		return null;
+	}
+	const match = /^gitdir:\s*(.+?)\s*$/m.exec(content);
+	if (match === null) return null;
+	const target = match[1];
+	return isAbsolute(target) ? target : resolve(root, target);
 }
 
-function watchWorkspace(root, key) {
+function watchWorkspace(root, key, workspaceId) {
 	const existing = watchers.get(key);
 	if (existing !== void 0) {
 		// live watcher, or a failed attempt still inside its retry backoff
-		if (existing.watcher !== null || Date.now() - existing.failedAt < config.watchRetryMs) return;
+		if (existing.watcher !== null || Date.now() - existing.failedAt < config.watchRetryMs) {
+			existing.workspaceId = workspaceId;
+			return;
+		}
+		// retrying: the degraded poll is replaced by a real watcher, or by a
+		// fresh one created below
+		if (existing.poll !== void 0) clearInterval(existing.poll);
 		watchers.delete(key);
 	}
 	// only git workspaces need a badge; a missing .git skips the watcher but
 	// retries on the normal backoff (cheap existsSync) so a later `git init`
-	// in the workspace is picked up
+	// in the workspace is picked up. No poll here: a non-repository has nothing
+	// to report.
 	if (!existsSync(join(root, ".git"))) {
-		watchers.set(key, { watcher: null, failedAt: Date.now(), timer: void 0 });
+		watchers.set(key, { watcher: null, extra: null, failedAt: Date.now(), timer: void 0, workspaceId });
 		return;
 	}
+	// Both watchers share one debounce and one failure path. Either dying means
+	// this workspace can no longer be trusted to be event-driven, so both are
+	// dropped and the degraded poll covers it until the retry backoff
+	// re-establishes them.
+	const onEvent = () => {
+		const record = watchers.get(key);
+		if (record === void 0) return;
+		clearTimeout(record.timer);
+		record.timer = setTimeout(() => notifyChange(key), config.debounceMs);
+	};
+	const onError = () => {
+		// The watcher died after being established (inotify budget, tree
+		// replaced, permissions). Drop it, but KEEP the record so the retry
+		// backoff and the degraded poll both have somewhere to live — and
+		// start polling so this workspace stays fresh in the meantime.
+		const current = watchers.get(key);
+		if (current === void 0) return;
+		closeWatchers(current);
+		current.failedAt = Date.now();
+		startFallbackPoll(key, root);
+	};
 	try {
-		// Watch the whole worktree, .git included: worktree edits (the most
-		// common dirty signal) and metadata ops (commit / checkout / stage)
-		// all surface here. The 200ms debounce collapses save bursts; if the
-		// tree is too large for the inotify budget the error handler drops
-		// back to the 60s client poll.
-		const watcher = watch(root, { recursive: true }, () => {
-			const record = watchers.get(key);
-			if (record === void 0) return;
-			clearTimeout(record.timer);
-			record.timer = setTimeout(() => notifyChange(key), config.debounceMs);
-		});
-		watcher.on("error", () => unwatchWorkspace(key));
-		watchers.set(key, { watcher, timer: void 0 });
+		// Watch the whole worktree: worktree edits (the most common dirty signal)
+		// surface here and the debounce collapses save bursts. In a MAIN worktree
+		// this covers git metadata too, because its git dir IS `<root>/.git`.
+		const watcher = watch(root, { recursive: true }, onEvent);
+		watcher.on("error", onError);
+		// A linked worktree's git dir is OUTSIDE root, so staging, committing and
+		// checking out there write nothing this watch can see. Watch it too; if it
+		// cannot be watched the root watch still covers file edits, and the
+		// degraded poll is not started for a merely partial loss.
+		const gitDir = outerGitDir(root);
+		let extra = null;
+		if (gitDir !== null) {
+			try {
+				extra = watch(gitDir, { recursive: true }, onEvent);
+				extra.on("error", onError);
+			} catch {
+				extra = null;
+			}
+		}
+		watchers.set(key, { watcher, extra, timer: void 0, workspaceId });
 	} catch {
-		// watch refused (permissions, watch budget) — remember and back off
-		watchers.set(key, { watcher: null, failedAt: Date.now(), timer: void 0 });
+		// watch refused (permissions, watch budget) — back off AND poll: this
+		// repository is real, just unwatchable
+		watchers.set(key, { watcher: null, extra: null, failedAt: Date.now(), timer: void 0, workspaceId });
+		startFallbackPoll(key, root);
 	}
 }
 
@@ -401,15 +600,66 @@ function watchWorkspace(root, key) {
 function syncWatchers(ctx) {
 	const wanted = new Set();
 	for (const entity of ctx.workspaceRegistry.list()) {
-		const p = entity?.record?.path ?? entity?.path;
-		if (typeof p !== "string") continue;
-		wanted.add(p);
-		watchWorkspace(p, p);
+		// `path` and `id` are the entity's public surface; its `record` is private
+		if (typeof entity?.path !== "string") continue;
+		wanted.add(entity.path);
+		watchWorkspace(entity.path, entity.path, entity.id === void 0 ? void 0 : String(entity.id));
 	}
 	for (const key of [...watchers.keys()]) if (!wanted.has(key)) unwatchWorkspace(key);
 }
 //#endregion
 
+/**
+ * Resolve a request to a registered workspace directory. The caller says WHO it
+ * is, never WHERE to look — no client-supplied path is trusted or probed.
+ *
+ *   1. `?workspace=<id>` — the entity's own id, which is the same id the sidebar
+ *      seam hands a row (the client builds `workspaceId` from `workspace.id`).
+ *   2. `?session=<id>` — registry membership first, because `sessionIds` is
+ *      header-validated and durable, so a conversation that is no longer live
+ *      still resolves; then the live session's cwd validated through the
+ *      registry's `resolveByPath`, which covers the window where a brand-new
+ *      session is not yet attached to its workspace.
+ *
+ * @returns `{ id, path }` when resolved, else `{ status, error: { code, message } }`.
+ *   The id is returned because the route echoes it: a client that asked by
+ *   SESSION needs the workspace id to attribute that workspace's SSE events,
+ *   since an event carries a workspace id and a session id can never match it.
+ */
+async function resolveWorkspace(ctx, params) {
+	const workspaceId = params.get("workspace") ?? "";
+	const sessionId = params.get("session") ?? "";
+	if (workspaceId === "" && sessionId === "") {
+		return { status: 400, error: { code: "target-required", message: "pass workspace=<id> or session=<id>" } };
+	}
+	const entities = [];
+	for (const entity of ctx.workspaceRegistry.list()) {
+		if (typeof entity?.path === "string") entities.push(entity);
+	}
+	if (workspaceId !== "") {
+		const entity = entities.find((candidate) => String(candidate.id) === workspaceId);
+		if (entity === void 0) {
+			return { status: 404, error: { code: "workspace-not-found", message: "no workspace with that id" } };
+		}
+		return { id: String(entity.id), path: entity.path };
+	}
+	for (const entity of entities) {
+		if (Array.isArray(entity.sessionIds) && entity.sessionIds.includes(sessionId)) {
+			return { id: String(entity.id), path: entity.path };
+		}
+	}
+	// A brand-new session whose workspace attach has not landed yet. Trust the
+	// server-side session header (never the caller), then require the registry to
+	// recognise that directory — so the path is still registry-validated.
+	const cwd = ctx.get("sessions")?.get?.(sessionId)?.header?.cwd;
+	const resolveByPath = ctx.workspaceRegistry.resolveByPath;
+	if (typeof cwd === "string" && cwd !== "" && typeof resolveByPath === "function") {
+		const entity = await resolveByPath.call(ctx.workspaceRegistry, cwd).catch(() => void 0);
+		if (entity !== void 0 && typeof entity?.path === "string") return { id: String(entity.id), path: entity.path };
+	}
+	return { status: 404, error: { code: "session-not-found", message: "no registered workspace owns that session" } };
+}
+
 /** Host plugin body — register the status route and the SSE change feed. */
 function apply(ctx) {
 	ctx.effect(() => ctx.webServer.register({
@@ -418,28 +668,23 @@ function apply(ctx) {
 		handler: async (req, res) => {
 			try {
 				const url = new URL(req.url, "http://localhost");
-				const raw = url.searchParams.get("path") ?? "";
-				if (raw === "") throw new Error("missing path");
-				// Allowlist: the requested path must be (or resolve to) a registered
-				// workspace directory. Anything else is refused without inspection.
-				const registered = new Set();
-				for (const entity of ctx.workspaceRegistry.list()) {
-					const p = entity?.record?.path ?? entity?.path;
-					if (typeof p === "string") registered.add(p);
-				}
-				const resolved = await realpath(raw).catch(() => null);
-				if (resolved === null || !registered.has(raw) && !registered.has(resolved)) {
-					res.writeHead(403, { "content-type": "application/json" });
-					res.end(JSON.stringify({ git: false, error: "path is not a registered workspace" }));
+				const target = await resolveWorkspace(ctx, url.searchParams);
+				if (target.error !== void 0) {
+					res.writeHead(target.status, { "content-type": "application/json" });
+					res.end(JSON.stringify({ git: false, error: target.error }));
 					return;
 				}
 				const detail = url.searchParams.get("detail") === "1";
-				const body = JSON.stringify(await gitStatus(resolved, detail));
+				const info = await gitStatus(target.path, detail);
+				// 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
+				// only ever refreshed on remount or the 60s poll.
 				res.writeHead(200, { "content-type": "application/json" });
-				res.end(body);
+				res.end(JSON.stringify({ ...info, workspace: target.id }));
 			} catch (error) {
 				res.writeHead(400, { "content-type": "application/json" });
-				res.end(JSON.stringify({ git: false, error: String(error?.message ?? error) }));
+				res.end(JSON.stringify({ git: false, error: { code: "bad-request", message: String(error?.message ?? error) } }));
 			}
 		}
 	}));
@@ -464,12 +709,12 @@ function apply(ctx) {
 				const stream = {
 					res,
 					heartbeat: null,
-					send: (key) => {
+					send: (payload) => {
 						try {
 							// NAMED frame: the client subscribes with
 							// addEventListener("change", …), which never sees an
 							// unnamed message
-							res.write(`event: change\ndata: ${JSON.stringify({ path: key })}\n\n`);
+							res.write(`event: change\ndata: ${JSON.stringify(payload)}\n\n`);
 						} catch {
 							/* socket gone; the close handler cleans up */
 						}
@@ -510,9 +755,11 @@ export {
 	config,
 	OPERATION_MARKERS,
 	operationMarker,
+	outerGitDir,
 	parseStatusV2,
 	runGit,
 	gitStatus,
+	resolveWorkspace,
 	watchWorkspace,
 	unwatchWorkspace,
 	syncWatchers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Git status badges for DeepSeek Harness: sidebar workspace rows (via the sidebar.workspaces.row seam) and an input-row chip showing the current conversation's workspace git state. Event-driven freshness over SSE.",
   "type": "module",
   "main": "lib/index.js",
@@ -48,6 +48,7 @@
     "cordis.patch.yml",
     "package.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "peerDependencies": {