dsh-git-badge 0.6.0 → 0.8.0

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,30 +28,47 @@
  *       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.
- *     - `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.
+ *     - 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, and `pr=1` adds the
+ *       branch's GitHub PR/CI state read through the user's own `gh` CLI. Both
+ *       serve the input chip only — the hover card and the PR token — so a
+ *       sidebar row refresh pays for neither. The PR read is TTL-bounded and
+ *       out of band, like the fetch; it degrades to an ABSENT field rather than
+ *       an error whenever `gh` cannot answer (see the PR region).
+ *     - `pr=1` requires `gh` on PATH and authenticated for a token to appear.
+ *       The plugin never handles the credential: `gh` owns it.
  *
  *   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 +91,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,
 	/**
@@ -76,23 +105,48 @@ const config = {
 	 * collapsed-fallback branch deterministically — a real sub-millisecond budget
 	 * would just race git's own startup.
 	 */
-	gitRunner: null
+	gitRunner: null,
+	/**
+	 * PR / CI status via the `gh` CLI: "auto" reads it where `gh` can answer and
+	 * silently shows nothing where it cannot; "off" never invokes `gh` at all.
+	 * Only the input chip asks for it, so a sidebar-only view spawns no forge
+	 * process — see the PR region.
+	 */
+	prStatus: "auto",
+	/** minimum interval between forge refreshes per repository */
+	prTtlMs: 90000,
+	/**
+	 * Forge call budget. Unlike git this is a network round trip to GitHub, so
+	 * it gets a more generous budget than the status sample — but it is bounded
+	 * all the same, because nothing here may hang the route.
+	 */
+	prTimeoutMs: 6000,
+	/**
+	 * Invoker for the `gh` CLI; null means the real runCli. The suite substitutes
+	 * one so every degradation path (no gh, logged out, no PR, garbage output,
+	 * timeout) is covered with no gh, no network and no forge.
+	 */
+	prRunner: null
 };
 
 /**
- * Run git in dir. Resolves { stdout } on success; on failure { stdout: null }
- * plus exactly one of: timeout (execFile timeout kill), missing (no git
- * binary), or exitCode (git ran and rejected — e.g. "not a repository").
- * The exitCode/timeout distinction separates a definitive answer (non-repo)
- * from a transient one (degraded).
+ * Run an external command in a directory. Resolves { stdout } on success; on
+ * failure { stdout: null } plus exactly one of: timeout (execFile timeout kill),
+ * missing (no such binary), or exitCode (the command ran and rejected — e.g.
+ * "not a repository", or `gh` reporting no pull request).
+ *
+ * The exitCode/timeout/missing trichotomy is what lets a CALLER tell a
+ * definitive answer from a transient one: a missing `gh` and a `gh` that says
+ * "no PR" are different facts, and only the caller knows which of them it can
+ * act on. Shared by git and `gh` so neither grows its own timeout semantics.
  */
-function runGit(dir, args, opts) {
-	const { env, timeout = config.gitTimeoutMs } = opts ?? {};
+function runCli(cmd, args, opts) {
+	const { cwd, env, timeout = config.gitTimeoutMs } = opts ?? {};
 	// env is a full replacement for execFile; overlay onto process.env so
 	// PATH/HOME (credential helpers, global config) survive
 	const fullEnv = env === void 0 ? void 0 : { ...process.env, ...env };
 	return new Promise((resolve) => {
-		execFile("git", args, { cwd: dir, timeout, env: fullEnv }, (error, stdout) => {
+		execFile(cmd, args, { cwd, timeout, env: fullEnv }, (error, stdout) => {
 			if (error === void 0 || error === null) resolve({ stdout: String(stdout) });
 			else if (error.killed) resolve({ stdout: null, timeout: true });
 			else if (error.code === "ENOENT") resolve({ stdout: null, missing: true });
@@ -101,6 +155,15 @@ function runGit(dir, args, opts) {
 	});
 }
 
+/**
+ * Run git in dir. A thin specialization of runCli: the contract above is
+ * unchanged, and `config.gitRunner` still substitutes for the whole call so the
+ * suite can force the timeout branch.
+ */
+function runGit(dir, args, opts) {
+	return runCli("git", args, { ...opts, cwd: dir });
+}
+
 /** Marker response for a git invocation that failed or timed out (transient). */
 const GIT_DEGRADED = { git: false, error: "git unavailable (timeout or failure)" };
 
@@ -154,6 +217,167 @@ async function maybeFetch(toplevel) {
 }
 //#endregion
 
+//#region PR / CI status (gh)
+/**
+ * GitHub pull-request and check state for the current branch, read through the
+ * user's own `gh` CLI.
+ *
+ * Why the CLI and not the REST API: `gh` already owns the user's credentials in
+ * its own config, so this plugin never reads, stores, caches or forwards a
+ * token. There is no secret here to leak and no OAuth flow to maintain — and a
+ * machine that has never authenticated `gh` simply gets no PR token.
+ *
+ * Degradation is a MISSING FIELD, never an error. A machine without `gh`, a
+ * logged-out `gh`, a remote that is not GitHub, an offline network, a forge rate
+ * limit, unparseable output and a timed-out call all produce exactly the same
+ * response: no `pr` key at all. That is the honest answer, because in every one
+ * of those cases the badge has nothing to say — and a caller that could tell
+ * "no PR" from "no gh" would still not know what to draw.
+ *
+ * Like the fetch above this is TTL-bounded and NEVER awaited by the route: the
+ * cached value is served immediately and a refresh that CHANGES it notifies
+ * subscribers, so the request that lapses the window carries the previous answer
+ * and the follow-up carries the new one. A forge round trip must never become
+ * badge latency.
+ */
+/** toplevel -> { lastAttemptAt, inFlight, value }; `value` undefined = nothing to say. */
+const prState = new Map();
+
+/** Test seam: the CLI invoker `gh` calls go through, so no test needs `gh`. */
+function runPrCli(cmd, args, opts) {
+	return (config.prRunner ?? runCli)(cmd, args, opts);
+}
+
+/**
+ * Does `origin` point at github.com? A cheap LOCAL call, so a non-GitHub repo
+ * never pays for a `gh` process. Deliberately scoped to origin: that is the
+ * remote `gh` itself resolves the repository from, so agreeing with it here is
+ * what keeps the two from disagreeing later.
+ */
+async function originIsGitHub(toplevel) {
+	const out = await runGit(toplevel, ["remote", "get-url", "origin"]);
+	if (out.stdout === null) return false;
+	return /(^|[/@.])github\.com[:/]/i.test(out.stdout.trim());
+}
+
+/**
+ * Reduce a `statusCheckRollup` to ONE worst-case state, so the chip needs a
+ * single colour rather than a list.
+ *
+ * Two entry shapes share the array: a CheckRun carries `status` + `conclusion`,
+ * a StatusContext carries `state` alone. A single failure outweighs any number
+ * of successes and pending checks — "mostly passing" is not a thing a red/green
+ * token can express — so failure returns immediately and pending only wins over
+ * an otherwise all-successful set.
+ */
+function summarizeChecks(checks) {
+	let sawAny = false;
+	let sawPending = false;
+	for (const check of checks) {
+		const state = String(check?.state ?? "").toUpperCase();
+		const status = String(check?.status ?? "").toUpperCase();
+		const conclusion = String(check?.conclusion ?? "").toUpperCase();
+		sawAny = true;
+		const failed =
+			["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(state) ||
+			["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(conclusion);
+		if (failed) return "failing";
+		// unfinished: a CheckRun that has not completed, or a StatusContext PENDING
+		if (state === "PENDING" || (status !== "" && status !== "COMPLETED")) sawPending = true;
+	}
+	if (!sawAny) return "none";
+	return sawPending ? "pending" : "passing";
+}
+
+/** The compact PR shape the chip renders, or undefined when there is nothing to say. */
+function summarizePr(json) {
+	if (json === null || typeof json !== "object") return void 0;
+	const number = Number.isFinite(json?.number) ? json.number : void 0;
+	if (number === void 0) return void 0;
+	const pr = {
+		number,
+		state: summarizeChecks(Array.isArray(json.statusCheckRollup) ? json.statusCheckRollup : []),
+		// draft and review state are separate from CI: a draft with green checks
+		// is not ready, and a blocked review is not a failing build
+		draft: json.isDraft === true,
+		open: String(json.state ?? "OPEN").toUpperCase() === "OPEN"
+	};
+	// omitted, not present-and-undefined: absence is the contract for "nothing to
+	// say" throughout this half, so a consumer tests the key, never the value
+	if (typeof json.reviewDecision === "string" && json.reviewDecision !== "") pr.review = json.reviewDecision;
+	// The chip links the token to the PR, so `url` is the one field that becomes an
+	// `href`: only http(s) is emitted, and anything else is omitted like every
+	// other "nothing to say" field, so a payload value cannot reach an anchor as a
+	// `javascript:` URL. The client re-checks before it builds the href — this half
+	// is the authority on what it vouches for, not the only guard.
+	if (typeof json.url === "string" && json.url !== "") {
+		try {
+			const { protocol } = new URL(json.url);
+			if (protocol === "http:" || protocol === "https:") pr.url = json.url;
+		} catch {
+			// not a URL at all — omitted, exactly like an absent one
+		}
+	}
+	return pr;
+}
+
+/**
+ * Read PR state for `branch`, or undefined. NEVER throws and never rejects: a
+ * forge is an optional luxury, so every failure path is "nothing to say".
+ */
+async function readPrStatus(toplevel, branch) {
+	// a detached HEAD is not a branch `gh` can resolve a PR for
+	if (typeof branch !== "string" || branch === "" || branch.startsWith("HEAD")) return void 0;
+	if (!(await originIsGitHub(toplevel))) return void 0;
+	const out = await runPrCli("gh", ["pr", "view", branch, "--json", "number,state,isDraft,reviewDecision,statusCheckRollup,url"], {
+		cwd: toplevel,
+		timeout: config.prTimeoutMs,
+		// GH_PROMPT_DISABLED: an auth prompt must never hang the refresh (the gh
+		// analogue of the git fetch's GIT_TERMINAL_PROMPT=0). The pager vars keep
+		// gh from waiting on a pager that will never answer, and NO_COLOR keeps
+		// escape codes out of the JSON.
+		env: { GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1" }
+	});
+	if (out.stdout === null) return void 0;
+	let json;
+	try {
+		json = JSON.parse(out.stdout);
+	} catch {
+		return void 0;
+	}
+	return summarizePr(json);
+}
+
+/**
+ * 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
+ * called only when the refreshed value CHANGES, so an unchanged answer costs one
+ * forge call per TTL and zero SSE traffic.
+ */
+function prStatusFor(toplevel, branch, notify) {
+	if (config.prStatus === "off") return void 0;
+	const now = Date.now();
+	const state = prState.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 readPrStatus(toplevel, branch).catch(() => void 0);
+		const changed = JSON.stringify(record.value ?? null) !== JSON.stringify(value ?? null);
+		record.lastAttemptAt = Date.now();
+		record.inFlight = null;
+		record.value = value;
+		if (changed) notify(toplevel);
+		return value;
+	})();
+	record.inFlight = inFlight;
+	prState.set(toplevel, record);
+	return record.value;
+}
+//#endregion
+
 /**
  * Parse `git status --porcelain=v2 --branch` output.
  * Headers: `# branch.head <name>` (or `(detached)`), `# branch.upstream
@@ -230,11 +454,17 @@ function operationMarker(gitDir) {
  * branch, dirty state, and ahead/behind counts (what git itself considers
  * dirty), not the subdirectory in isolation. Intentional.
  *
- * `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.
+ * 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` serves the input chip's HOVER CARD (recent commits + stash) and
+ * `wantPr` its PR/CI token. They are asked for separately and by the chip only,
+ * so neither is paid for by a sidebar row refresh: a row needs status and
+ * identity, nothing more.
  */
-async function gitStatus(dir, wantDetail) {
+async function gitStatus(dir, wantDetail, wantPr) {
 	// one invocation answers both questions: the repository root (so a
 	// subdirectory workspace reports the whole repo) and the per-worktree git
 	// dir (where the operation markers above live)
@@ -248,6 +478,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 +504,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 +538,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
 	};
@@ -314,15 +561,25 @@ async function gitStatus(dir, wantDetail) {
 			if (count > 0) info.stashCount = count;
 		}
 	}
+	// PR / CI is the INPUT CHIP's business, so it is asked for explicitly
+	// (`?pr=1`) rather than paid for by every sidebar row: a row that surveys
+	// twenty workspaces must not spawn twenty forge processes. Served from the
+	// TTL cache and refreshed out of band, exactly like the fetch above — the
+	// forge round trip is never route latency.
+	if (wantPr) {
+		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
+		if (pr !== void 0) info.pr = pr;
+	}
 	return info;
 }
 
 //#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 +587,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 +615,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();
 }
 
-function watchWorkspace(root, key) {
+/**
+ * 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, 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 +810,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 +878,24 @@ 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 pr = url.searchParams.get("pr") === "1";
+				const info = await gitStatus(target.path, detail, pr);
+				// 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 +920,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 +966,17 @@ export {
 	config,
 	OPERATION_MARKERS,
 	operationMarker,
+	outerGitDir,
 	parseStatusV2,
+	runCli,
 	runGit,
 	gitStatus,
+	resolveWorkspace,
+	readPrStatus,
+	summarizePr,
+	summarizeChecks,
+	prStatusFor,
+	prState,
 	watchWorkspace,
 	unwatchWorkspace,
 	syncWatchers,