dsh-git-badge 0.7.0 → 0.9.0

package/lib/index.js

@@ -44,9 +44,14 @@
  *       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.
+ *     - `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
@@ -84,6 +89,15 @@ const config = {
 	fetchTtlMs: 60000,
 	/** fs-event burst collapse window */
 	debounceMs: 200,
+	/**
+	 * Coalescing window for identical status reads. 0 (the default) collapses only
+	 * CONCURRENT identical reads — which is exactly what a burst of sidebar
+	 * session rows mounting together produces — and leaves sequential reads
+	 * honest, so a caller that mutates a repository and asks again always sees the
+	 * new state. Raise it to also absorb serial bursts, at the cost of serving a
+	 * change up to that many milliseconds late.
+	 */
+	statusCacheMs: 0,
 	/** backoff before re-attempting a failed watcher (or a missing .git) */
 	watchRetryMs: 60000,
 	/**
@@ -100,23 +114,63 @@ 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,
+	/**
+	 * Bound on the repository-wide open-PR read (`gh pr list`). Only one page is
+	 * read, so a repository with more open PRs than this simply has the excess
+	 * invisible to worktree selection; the checkout's own PR read is unaffected.
+	 */
+	prListLimit: 50,
+	/**
+	 * Worktree-aware status: "auto" lets a SESSION-targeted badge follow the one
+	 * linked worktree whose branch has an open PR, so a conversation doing its
+	 * work in a worktree reports that tree instead of the main checkout its
+	 * directory names; "off" always reports the session's own directory. A
+	 * workspace-targeted row never follows a worktree whatever this is set to — a
+	 * row surveys the checkout the registry owns. See effectiveTarget.
+	 */
+	worktreeStatus: "auto"
 };
 
 /**
- * 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 });
@@ -125,6 +179,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)" };
 
@@ -178,6 +241,279 @@ 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;
+	// GitHub's OWN merge verdict (CLEAN / BLOCKED / BEHIND / DIRTY / DRAFT /
+	// UNSTABLE / HAS_HOOKS / UNKNOWN), passed through rather than re-derived here:
+	// whether a PR is mergeable depends on branch protection and required reviews,
+	// which is the forge's business and not this plugin's to interpret. `gh pr list`
+	// does not ask for it, so a worktree-candidate entry simply has no `mergeState`
+	// — absence is the contract, as everywhere else in this half.
+	if (typeof json.mergeStateStatus === "string" && json.mergeStateStatus !== "") pr.mergeState = json.mergeStateStatus.toUpperCase();
+	// 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,mergeStateStatus"], {
+		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);
+}
+
+/** toplevel -> { lastAttemptAt, inFlight, value: Map<branch, pr> }. */
+const prListState = new Map();
+
+/**
+ * Every OPEN pull request in `toplevel`'s repository, keyed by its head branch.
+ * ONE `gh pr list` answers the whole repository, which is what makes worktree
+ * selection affordable: N worktrees cost one forge call, not N.
+ *
+ * Degrades exactly like readPrStatus, and for the same reason: a non-array body,
+ * unparseable output, a logged-out `gh`, a non-GitHub `origin` and a timeout all
+ * resolve an empty map. "No PRs" and "no forge" are the same answer here — both
+ * mean no worktree can be shown to be the one the session is working in.
+ */
+async function readOpenPrs(toplevel) {
+	if (!(await originIsGitHub(toplevel))) return new Map();
+	const out = await runPrCli("gh", ["pr", "list", "--state", "open", "--limit", String(config.prListLimit), "--json", "number,headRefName,state,isDraft,reviewDecision,statusCheckRollup,url"], {
+		cwd: toplevel,
+		timeout: config.prTimeoutMs,
+		env: { GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1" }
+	});
+	if (out.stdout === null) return new Map();
+	let json;
+	try {
+		json = JSON.parse(out.stdout);
+	} catch {
+		return new Map();
+	}
+	if (!Array.isArray(json)) return new Map();
+	const byBranch = new Map();
+	for (const row of json) {
+		const branch = row?.headRefName;
+		if (typeof branch !== "string" || branch === "") continue;
+		const pr = summarizePr(row);
+		if (pr !== void 0) byBranch.set(branch, pr);
+	}
+	return byBranch;
+}
+
+/** Order-insensitive identity for an open-PR set, so "did it change?" is exact. */
+function prListKey(byBranch) {
+	if (byBranch === void 0) return "";
+	return JSON.stringify([...byBranch].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+/**
+ * Open PRs for toplevel: the value to serve NOW (possibly undefined), spawning an
+ * out-of-band refresh when the TTL has lapsed — the same shape and the same
+ * reasoning as prStatusFor, because the forge is never route latency.
+ *
+ * `notify` fires only when the set CHANGES: a changed set can change which
+ * worktree a session badge follows, so the client has to be told to refetch
+ * rather than waiting for its 60s safety-net poll.
+ */
+function openPrsFor(toplevel, notify) {
+	if (config.prStatus === "off") return void 0;
+	const now = Date.now();
+	const state = prListState.get(toplevel);
+	if (state !== void 0) {
+		// Fresh, or a refresh is already running: serve what we have either way.
+		if (now - state.lastAttemptAt < config.prTtlMs || state.inFlight !== null) return state.value;
+	}
+	const record = { lastAttemptAt: now, inFlight: null, value: state?.value };
+	const inFlight = (async () => {
+		const value = await readOpenPrs(toplevel).catch(() => void 0);
+		if (value !== void 0) {
+			const changed = prListKey(record.value) !== prListKey(value);
+			record.value = value;
+			if (changed) notify(toplevel);
+		}
+		record.lastAttemptAt = Date.now();
+		record.inFlight = null;
+		return value;
+	})();
+	record.inFlight = inFlight;
+	prListState.set(toplevel, record);
+	return record.value;
+}
+
+/**
+ * The one linked worktree a session badge may follow: exactly one entry other
+ * than the checkout itself that is checked out on a branch with an OPEN PR.
+ *
+ * Exactly one, because the plugin cannot know which tree a session uses — DSH
+ * records no session→worktree link at all — so an ambiguous repository stays on
+ * its own checkout rather than guessing. A second open PR is a reason to say
+ * nothing, not a reason to pick one. Detached, bare and prunable entries are
+ * never candidates: they have no branch a PR could belong to.
+ */
+function selectSessionWorktree(worktrees, openPrs, checkoutPath) {
+	if (openPrs === void 0 || openPrs.size === 0) return void 0;
+	const candidates = worktrees.filter((wt) =>
+		wt.path !== checkoutPath &&
+		wt.detached !== true &&
+		wt.bare !== true &&
+		wt.prunable !== true &&
+		typeof wt.branch === "string" &&
+		openPrs.has(wt.branch)
+	);
+	return candidates.length === 1 ? candidates[0] : void 0;
+}
+
+/**
+ * PR state for toplevel: the value to serve NOW (possibly undefined, possibly
+ * stale), spawning an out-of-band refresh when the TTL has lapsed. `notify` is
+ * called only when the refreshed value CHANGES, so an unchanged answer costs one
+ * forge call per TTL and zero SSE traffic.
+ *
+ * Keyed by BRANCH as well as toplevel: a checkout inside the TTL window would
+ * otherwise be served the PR of the branch it was on when the window opened.
+ */
+function prStatusFor(toplevel, branch, notify) {
+	if (config.prStatus === "off") return void 0;
+	const now = Date.now();
+	const key = toplevel + "\u0000" + branch;
+	const state = prState.get(key);
+	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(key, record);
+	return record.value;
+}
+//#endregion
+
 /**
  * Parse `git status --porcelain=v2 --branch` output.
  * Headers: `# branch.head <name>` (or `(detached)`), `# branch.upstream
@@ -214,6 +550,86 @@ function parseStatusV2(out) {
 	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked };
 }
 
+/**
+ * Parse `git worktree list --porcelain`. Blocks of `key value` lines separated by
+ * a blank line: `worktree <path>`, `HEAD <sha>`, `branch refs/heads/<name>` (the
+ * line is ABSENT when the entry is detached), and the flag lines `bare`, `locked`
+ * and `prunable`, which may carry a reason after the key.
+ *
+ * The last field is the checkout's directory NAME, which is all the badge ever
+ * reports — never the path (AGENTS.md rule 7). Git prints the main worktree first,
+ * but the caller identifies the checkout it is standing in by comparing `path`
+ * against its own toplevel rather than by list position.
+ */
+function parseWorktreeList(stdout) {
+	const entries = [];
+	let entry = null;
+	const flush = () => {
+		if (entry !== null) entries.push({ ...entry, name: basename(entry.path) });
+		entry = null;
+	};
+	for (const raw of String(stdout ?? "").split("\n")) {
+		const line = raw.trim();
+		if (line === "") {
+			flush();
+			continue;
+		}
+		const at = line.indexOf(" ");
+		const key = at === -1 ? line : line.slice(0, at);
+		const value = at === -1 ? "" : line.slice(at + 1);
+		if (key === "worktree") {
+			flush();
+			entry = { path: value, head: "", branch: void 0, detached: false, bare: false, locked: false, prunable: false };
+			continue;
+		}
+		if (entry === null) continue;
+		if (key === "HEAD") entry.head = value;
+		else if (key === "branch") entry.branch = value.replace(/^refs\/heads\//, "");
+		else if (key === "detached") entry.detached = true;
+		else if (key === "bare") entry.bare = true;
+		else if (key === "locked") entry.locked = true;
+		else if (key === "prunable") entry.prunable = true;
+	}
+	flush();
+	return entries;
+}
+
+/**
+ * The worktree landscape of the repository `dir` sits in: its toplevel in GIT's
+ * own spelling (so it compares exactly against the listed paths, with no
+ * spelling guesswork) and every worktree of that repository, main one included.
+ *
+ * Two cheap local invocations. A failure of either degrades to "no linked
+ * worktrees", which leaves the badge on the directory the session actually names
+ * rather than substituting a guess.
+ */
+async function readWorktrees(dir) {
+	const top = await runGit(dir, ["rev-parse", "--show-toplevel"]);
+	const toplevel = top.stdout === null ? "" : top.stdout.trim();
+	if (toplevel === "") return { toplevel: "", worktrees: [] };
+	const list = await runGit(dir, ["worktree", "list", "--porcelain"]);
+	return { toplevel, worktrees: list.stdout === null ? [] : parseWorktreeList(list.stdout) };
+}
+
+/** In-flight worktree probes, so a burst of callers shares one pair of calls. */
+const worktreeInFlight = new Map();
+
+/**
+ * `readWorktrees` with identical CONCURRENT calls collapsed, the same way
+ * `gitStatus` collapses status reads: every session row of one workspace probes
+ * the same directory at the same moment. Deliberately no TTL — the probe is two
+ * local git calls, and a worktree created a moment ago must be visible at once.
+ */
+function worktreesFor(dir) {
+	const pending = worktreeInFlight.get(dir);
+	if (pending !== void 0) return pending;
+	const run = readWorktrees(dir).finally(() => {
+		worktreeInFlight.delete(dir);
+	});
+	worktreeInFlight.set(dir, run);
+	return run;
+}
+
 /**
  * In-progress operation markers, in precedence order. Git drops one of these in
  * the per-worktree git dir while an operation is paused; the first match names
@@ -259,11 +675,12 @@ function operationMarker(gitDir) {
  * 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.
+ * `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 gitStatusUncached(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)
@@ -360,9 +777,54 @@ 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;
 }
 
+/** In-flight status reads, so N callers asking at once share one `git status`. */
+const statusInFlight = new Map();
+/** Completed reads inside `config.statusCacheMs`; unused at the 0 default. */
+const statusCache = new Map();
+
+/**
+ * Status for dir, with identical CONCURRENT reads collapsed into one. That is the
+ * shape a burst of sidebar session rows produces when they mount together: N rows
+ * of one workspace resolve to the same directory, and without this they would run
+ * N `git status` walks of the same tree at the same instant.
+ *
+ * The optional `statusCacheMs` window extends the collapse to serial bursts. It
+ * defaults to 0 on purpose: a cache that outlives the call would let a caller
+ * that mutates a repository and asks again read a stale answer, and correctness
+ * of a *status* badge outranks saving a walk.
+ */
+function gitStatus(dir, wantDetail, wantPr) {
+	const key = dir + "\u0000" + (wantDetail === true) + "\u0000" + (wantPr === true);
+	if (config.statusCacheMs > 0) {
+		const hit = statusCache.get(key);
+		if (hit !== void 0 && Date.now() - hit.at < config.statusCacheMs) return Promise.resolve(hit.value);
+	}
+	const pending = statusInFlight.get(key);
+	if (pending !== void 0) return pending;
+	const run = gitStatusUncached(dir, wantDetail, wantPr)
+		.then((value) => {
+			if (config.statusCacheMs > 0) statusCache.set(key, { at: Date.now(), value });
+			return value;
+		})
+		.finally(() => {
+			statusInFlight.delete(key);
+		});
+	statusInFlight.set(key, run);
+	return run;
+}
+
 //#region git-state watcher
 /**
  * One recursive watcher per workspace, plus a second one when the git dir lives
@@ -596,6 +1058,49 @@ function watchWorkspace(root, key, workspaceId) {
 	}
 }
 
+/**
+ * Workspace path -> { worktreePath, workspaceId, owned } for the inferred
+ * worktree a session badge is currently following. One per workspace: selection
+ * is a single choice by construction (selectSessionWorktree), so following a
+ * different tree retires the previous one here.
+ */
+const selectedWorktrees = new Map();
+
+/**
+ * Keep the watcher set aligned with the worktree a session badge has been told to
+ * follow.
+ *
+ * A selected worktree is usually NOT a registered workspace, so nothing else
+ * watches it — and freshness would then depend on the owning checkout's recursive
+ * watch happening to cover it (true for a worktree nested inside the repository,
+ * false for a sibling directory). Its events must also carry the OWNING workspace
+ * id, because that is what a session-targeted client matches its events against:
+ * `notifyChange` reads the id off the watcher record for the path it watched.
+ *
+ * `owned` records whether this call created the watcher. A worktree can itself be
+ * a registered workspace (someone may have opened one as a workspace), and
+ * retiring the selection must never tear down a watcher the registry owns.
+ *
+ * Idempotent and cheap: called on every session request, and a no-op while the
+ * selection is unchanged. `chosenPath === undefined` retires whatever was
+ * selected — the "the worktree is gone, or its PR closed" path.
+ */
+function selectWorktreeWatch(ownerPath, workspaceId, chosenPath) {
+	const previous = selectedWorktrees.get(ownerPath);
+	if (previous !== void 0 && previous.worktreePath === chosenPath) {
+		previous.workspaceId = workspaceId;
+		return;
+	}
+	if (previous !== void 0) {
+		if (previous.owned) unwatchWorkspace(previous.worktreePath);
+		selectedWorktrees.delete(ownerPath);
+	}
+	if (chosenPath === undefined) return;
+	const owned = !watchers.has(chosenPath);
+	watchWorkspace(chosenPath, chosenPath, workspaceId);
+	selectedWorktrees.set(ownerPath, { worktreePath: chosenPath, workspaceId, owned });
+}
+
 /** Reconcile the watcher set with the current workspace registry. */
 function syncWatchers(ctx) {
 	const wanted = new Set();
@@ -605,6 +1110,17 @@ function syncWatchers(ctx) {
 		wanted.add(entity.path);
 		watchWorkspace(entity.path, entity.path, entity.id === void 0 ? void 0 : String(entity.id));
 	}
+	// An inferred worktree is watched because a session request selected it, not
+	// because the registry owns it. Keep the ones whose owner is still registered
+	// and retire the rest, so this reconcile never tears down a live selection.
+	for (const [ownerPath, entry] of selectedWorktrees) {
+		if (!wanted.has(ownerPath)) {
+			if (entry.owned) unwatchWorkspace(entry.worktreePath);
+			selectedWorktrees.delete(ownerPath);
+			continue;
+		}
+		wanted.add(entry.worktreePath);
+	}
 	for (const key of [...watchers.keys()]) if (!wanted.has(key)) unwatchWorkspace(key);
 }
 //#endregion
@@ -660,6 +1176,46 @@ async function resolveWorkspace(ctx, params) {
 	return { status: 404, error: { code: "session-not-found", message: "no registered workspace owns that session" } };
 }
 
+/**
+ * The directory a request is ABOUT.
+ *
+ * A SESSION-targeted chip may follow the one linked worktree its repository can be
+ * shown to be working in (selectSessionWorktree): DSH records no session→worktree
+ * link at all — session cwd is immutable creation metadata and `attachSession`
+ * requires it to equal the workspace path — so a conversation started in the main
+ * checkout would otherwise report `main` while its work, and its pull request,
+ * live in a tree. The tree's watcher is reconciled HERE, because this is the only
+ * place that knows which tree was chosen.
+ *
+ * A WORKSPACE-targeted row never follows a worktree: a row surveys the checkout
+ * the registry owns, and substituting a tree would make the row lie about the
+ * branch it is on.
+ *
+ * Gated three ways so the common case costs nothing: the caller must name a
+ * session, must be asking about PR state at all (selection is defined by an open
+ * PR, so a caller not asking cannot benefit), and the repository must actually
+ * have a linked worktree. Only then is the forge consulted.
+ */
+async function effectiveTarget(target, bySession, wantPr, notify) {
+	if (bySession !== true || wantPr !== true || config.worktreeStatus === "off") return { id: target.id, path: target.path };
+	const { toplevel, worktrees } = await worktreesFor(target.path);
+	// Git lists the main worktree first, so `main.path === toplevel` is the exact
+	// test for "the session's own directory is the main checkout". A session whose
+	// directory IS a linked worktree is its own answer and is never swapped
+	// sideways onto a sibling.
+	const main = worktrees[0];
+	if (toplevel === "" || main === void 0 || main.path !== toplevel || worktrees.length <= 1) {
+		selectWorktreeWatch(target.path, target.id, void 0);
+		return { id: target.id, path: target.path };
+	}
+	const openPrs = openPrsFor(toplevel, notify);
+	const chosen = selectSessionWorktree(worktrees, openPrs, toplevel);
+	selectWorktreeWatch(target.path, target.id, chosen === void 0 ? void 0 : chosen.path);
+	if (chosen === void 0) return { id: target.id, path: target.path };
+	// The name and branch travel; the PATH never does (AGENTS.md rule 7).
+	return { id: target.id, path: chosen.path, worktree: { name: chosen.name, branch: chosen.branch } };
+}
+
 /** Host plugin body — register the status route and the SSE change feed. */
 function apply(ctx) {
 	ctx.effect(() => ctx.webServer.register({
@@ -675,13 +1231,44 @@ function apply(ctx) {
 					return;
 				}
 				const detail = url.searchParams.get("detail") === "1";
-				const info = await gitStatus(target.path, detail);
+				const pr = url.searchParams.get("pr") === "1";
+				// WHO asked decides whether a linked worktree may stand in for the
+				// session's own directory — see effectiveTarget. A workspace-targeted
+				// row never leaves the checkout the registry owns.
+				const session = url.searchParams.get("session");
+				const effective = await effectiveTarget(target, session !== null && session !== "", pr, notifyChange);
+				const info = await gitStatus(effective.path, detail, pr);
+				const body = { ...info, workspace: target.id };
+				if (effective.worktree !== void 0 && info.git === true) {
+					// The status describes a worktree the SESSION's directory does not
+					// name. Saying so is the whole honesty of the feature: the chip's
+					// mark says "worktree", its name says which, and this flag tells the
+					// card why the checkout below differs from the branch beside it.
+					body.worktreeInferred = true;
+					if (detail) {
+						// The session's OWN directory, for the card's `checkout` row, so the
+						// main checkout stays visible once the badge follows a tree. Gated
+						// by detail=1 (a pointer resting on the chip), so nothing at rest
+						// pays for the second read.
+						const own = await gitStatus(target.path, false, false);
+						if (own.git === true) {
+							body.checkout = {
+								branch: own.branch,
+								dirty: own.dirty,
+								changedFiles: own.changedFiles,
+								untrackedFiles: own.untrackedFiles,
+								ahead: own.ahead,
+								behind: own.behind
+							};
+						}
+					}
+				}
 				// 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(JSON.stringify({ ...info, workspace: target.id }));
+				res.end(JSON.stringify(body));
 			} catch (error) {
 				res.writeHead(400, { "content-type": "application/json" });
 				res.end(JSON.stringify({ git: false, error: { code: "bad-request", message: String(error?.message ?? error) } }));
@@ -757,9 +1344,27 @@ export {
 	operationMarker,
 	outerGitDir,
 	parseStatusV2,
+	parseWorktreeList,
+	readWorktrees,
+	worktreesFor,
+	runCli,
 	runGit,
 	gitStatus,
+	gitStatusUncached,
 	resolveWorkspace,
+	effectiveTarget,
+	readPrStatus,
+	summarizePr,
+	summarizeChecks,
+	prStatusFor,
+	prState,
+	readOpenPrs,
+	openPrsFor,
+	prListState,
+	selectSessionWorktree,
+	selectWorktreeWatch,
+	selectedWorktrees,
+	statusInFlight,
 	watchWorkspace,
 	unwatchWorkspace,
 	syncWatchers,