@zhuxixi/pi-agent-board 0.4.2 → 0.5.0

package/src/core/follow-up-queue.mjs

@@ -5,6 +5,24 @@ import { truncate } from "./heuristics.mjs";
 import { withViewLockSync } from "./locks.mjs";
 import * as P from "./paths.mjs";
 
+/**
+ * Run a queue mutation under the view lock, translating any failure (lock
+ * unavailable, fs errors inside the mutation) into {ok:false} so callers on
+ * the {ok} convention never see a throw (issue #33).
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {() => T} fn
+ * @returns {T | { ok: false, error: string }}
+ */
+function lockedQueueOp(root, viewId, fn) {
+	try {
+		return withViewLockSync(root, viewId, "queue", fn);
+	} catch (err) {
+		return { ok: false, error: `follow-up queue lock unavailable: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}
+
 /** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").FollowUpQueue} */
 export function emptyFollowUpQueue(viewId, now = Date.now()) {
 	return { version: 1, viewId, nextSeq: 1, updatedAt: now, items: [] };
@@ -41,7 +59,7 @@ export function summarizeFollowUpQueue(queue) {
 export function enqueueFollowUp(root, viewId, text, opts = {}) {
 	const clean = String(text || "").trim();
 	if (!clean) return { ok: false, error: "Empty follow-up" };
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const now = Date.now();
 		const item = {
@@ -70,7 +88,7 @@ export function enqueueFollowUp(root, viewId, text, opts = {}) {
 
 /** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
 export function claimNextFollowUp(root, viewId, opts = {}) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const item = queue.items.filter((i) => i.status === "queued").sort((a, b) => a.seq - b.seq)[0];
 		if (!item) return { ok: false, error: "No queued follow-up" };
@@ -114,7 +132,7 @@ export function releaseFollowUp(root, viewId, itemId) {
 
 /** @param {string} root @param {string} viewId */
 export function removeLastFollowUp(root, viewId) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const queued = queue.items.filter((i) => i.status === "queued").sort((a, b) => b.seq - a.seq);
 		const last = queued[0];
@@ -128,7 +146,7 @@ export function removeLastFollowUp(root, viewId) {
 
 /** @param {string} root @param {string} viewId */
 export function clearQueuedFollowUps(root, viewId) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		let cancelled = 0;
 		for (const item of queue.items) {
@@ -145,7 +163,7 @@ export function clearQueuedFollowUps(root, viewId) {
 
 /** @param {string} root @param {string} viewId @param {string} itemId @param {(item: import("./types.mjs").FollowUpItem) => void} mutate */
 function updateItem(root, viewId, itemId, mutate) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const item = queue.items.find((i) => i.id === itemId);
 		if (!item) return { ok: false, error: "Unknown follow-up" };

package/src/core/host-crash.mjs

@@ -0,0 +1,39 @@
+/**
+ * Crash-time finalization for PTY hosts (used by pty-runner's uncaughtException
+ * handler). Pure enough to unit-test: writes a failed host.json + a diagnostic.
+ * Never throws — this runs on the crash path.
+ */
+import { appendDiagnostic } from "./diagnostics.mjs";
+import { writeHost } from "./store.mjs";
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {object|null} host
+ * @param {unknown} error
+ * @returns {object}
+ */
+export function finalizeHostCrash(root, viewId, host, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	const failed = {
+		...(host ?? { version: 1, viewId, mode: "pty", socketPath: null, startedAt: Date.now() }),
+		state: "failed",
+		endedAt: Date.now(),
+		lastSeenAt: Date.now(),
+		exitCode: 1,
+		error: message,
+	};
+	try {
+		writeHost(root, failed);
+	} catch { /* best effort */ }
+	try {
+		appendDiagnostic(root, viewId, {
+			source: "runner",
+			level: "error",
+			code: "host_crashed",
+			message: `PTY host crashed: ${message}`,
+			details: { error: message },
+		});
+	} catch { /* best effort */ }
+	return failed;
+}

package/src/core/locks.mjs

@@ -1,6 +1,14 @@
 /**
  * Tiny dependency-free synchronous file lock helpers for local agent-board artifacts.
  * Locks use atomic mkdir on a sibling .lock directory and are cleaned up in finally.
+ *
+ * Failure model (issue #33): acquisition failures are classified.
+ * - EEXIST (contention): wait in 20ms ticks until the stale window passes, then
+ *   force-steal (bounded to MAX_STEAL_ATTEMPTS). This preserves the original
+ *   wait/steal contract (see test/locks.test.mjs).
+ * - Anything else (deleted parent, read-only fs, permissions, disk full, ...):
+ *   MAX_ENV_ATTEMPTS quick retries — each retry re-runs ensureDir so a parent
+ *   deleted mid-acquisition self-heals — then throw LOCK_TIMEOUT. Never spin.
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
@@ -8,22 +16,33 @@ import { ensureDir } from "./atomic.mjs";
 import * as P from "./paths.mjs";
 
 const DEFAULT_STALE_MS = 30_000;
+/** Minimum contention window before a fresh lock can be force-stolen. */
+const MIN_WINDOW_MS = 250;
+const WAIT_TICK_MS = 20;
+/** Max stale-lock steal attempts before giving up. */
+const MAX_STEAL_ATTEMPTS = 2;
+/** Max quick retries for environmental failures before giving up. */
+const MAX_ENV_ATTEMPTS = 3;
+
+export const defaultLocksFs = Object.freeze({ existsSync, mkdirSync, readFileSync, rmSync, writeFileSync });
 
 /**
  * @template T
  * @param {string} lockPath
  * @param {() => T} fn
- * @param {{ staleMs?: number }} [opts]
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
  * @returns {T}
  */
 export function withFileLockSync(lockPath, fn, opts = {}) {
-	const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
-	acquireLock(lockPath, staleMs);
+	const fs = opts.fs ?? defaultLocksFs;
+	acquireLock(lockPath, opts.staleMs ?? DEFAULT_STALE_MS, fs);
+	let result;
 	try {
-		return fn();
+		result = fn();
 	} finally {
-		releaseLock(lockPath);
+		releaseLock(lockPath, fs);
 	}
+	return result;
 }
 
 /**
@@ -32,37 +51,74 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
  * @param {string} viewId
  * @param {string} name
  * @param {() => T} fn
- * @param {{ staleMs?: number }} [opts]
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
  * @returns {T}
  */
 export function withViewLockSync(root, viewId, name, fn, opts = {}) {
 	return withFileLockSync(P.viewLockPath(root, viewId, name), fn, opts);
 }
 
-/** @param {string} lockPath @param {number} staleMs */
-function acquireLock(lockPath, staleMs) {
-	ensureDir(path.dirname(lockPath));
-	const started = Date.now();
-	while (true) {
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function acquireLock(lockPath, staleMs, fs) {
+	const deadline = Date.now() + Math.max(MIN_WINDOW_MS, staleMs);
+	let steals = 0;
+	let envAttempts = 0;
+	for (;;) {
+		let created = false;
 		try {
-			mkdirSync(lockPath);
-			writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }), "utf8");
+			// Re-run every attempt: a parent deleted mid-acquisition self-heals here.
+			ensureDir(path.dirname(lockPath));
+			fs.mkdirSync(lockPath);
+			created = true;
+			fs.writeFileSync(
+				path.join(lockPath, "owner.json"),
+				JSON.stringify({ pid: process.pid, at: Date.now() }),
+				"utf8",
+			);
 			return;
 		} catch (err) {
-			if (!isLockStale(lockPath, staleMs) && Date.now() - started < Math.max(250, staleMs)) {
-				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+			if (err && err.code === "EEXIST") {
+				const expired = Date.now() >= deadline;
+				if (isLockStale(lockPath, staleMs, fs) || expired) {
+					if (steals >= MAX_STEAL_ATTEMPTS) {
+						throw lockError(lockPath, `stale lock could not be stolen after ${steals} attempts`);
+					}
+					steals += 1;
+					releaseLock(lockPath, fs);
+					continue;
+				}
+				sleep(WAIT_TICK_MS);
 				continue;
 			}
-			releaseLock(lockPath);
+			// Environmental failure: bounded quick retries, then fail fast.
+			if (created) releaseLock(lockPath, fs);
+			envAttempts += 1;
+			if (envAttempts >= MAX_ENV_ATTEMPTS) {
+				const reason = (err && (err.code || err.message)) || "unknown error";
+				throw lockError(lockPath, `lock path unusable (${reason})`);
+			}
+			sleep(WAIT_TICK_MS);
 		}
 	}
 }
 
-/** @param {string} lockPath @param {number} staleMs */
-function isLockStale(lockPath, staleMs) {
+/** @param {string} lockPath @param {string} reason */
+function lockError(lockPath, reason) {
+	const err = new Error(`file lock unavailable: ${lockPath} (${reason})`);
+	err.code = "LOCK_TIMEOUT";
+	return err;
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function isLockStale(lockPath, staleMs, fs) {
 	try {
-		if (!existsSync(lockPath)) return false;
-		const raw = readFileSync(path.join(lockPath, "owner.json"), "utf8");
+		if (!fs.existsSync(lockPath)) return false;
+		const raw = fs.readFileSync(path.join(lockPath, "owner.json"), "utf8");
 		const owner = JSON.parse(raw);
 		return Date.now() - Number(owner.at ?? 0) > staleMs;
 	} catch {
@@ -70,10 +126,10 @@ function isLockStale(lockPath, staleMs) {
 	}
 }
 
-/** @param {string} lockPath */
-function releaseLock(lockPath) {
+/** @param {string} lockPath @param {typeof defaultLocksFs} fs */
+function releaseLock(lockPath, fs) {
 	try {
-		rmSync(lockPath, { recursive: true, force: true });
+		fs.rmSync(lockPath, { recursive: true, force: true });
 	} catch {
 		/* best effort */
 	}

package/src/core/paths.mjs

@@ -23,6 +23,8 @@ export const launchPrefsPath = (root) => path.join(root, "launch-prefs.json");
 export const gcHistoryPath = (root) => path.join(root, "gc-history.jsonl");
 /** @param {string} root */
 export const cwdStatsPath = (root) => path.join(root, "cwd-stats.json");
+/** @param {string} root */
+export const providersPath = (root) => path.join(root, "providers.json");
 
 /** @param {string} root */
 export const viewsDir = (root) => path.join(root, "views");
@@ -40,8 +42,27 @@ export const hostConfigPath = (root, viewId) => path.join(viewDir(root, viewId),
 export const titleConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "title-config.json");
 /** @param {string} root @param {string} viewId */
 export const autoStateConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "auto-state-config.json");
+/**
+ * Named pipe used for the host control socket on Windows. Named pipes are kernel
+ * objects, not filesystem entries, so existsSync/unlink never apply to them; they
+ * vanish automatically when the owning process exits. Names must be ≤ 256 chars.
+ * @param {string} viewId
+ */
+export const controlPipeName = (viewId) => `\\\\.\\pipe\\pi-agent-board-${viewId}`;
+/**
+ * Control socket address for a view, platform-aware. On Windows plain filesystem
+ * paths cannot be bound by node's net module (EACCES) — only `\\.\pipe\`-style
+ * names work (see libuv#458, nodejs/node#55979).
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ * @param {string} viewId
+ */
+export function controlSocketPathFor(platform, root, viewId) {
+	if (platform === "win32") return controlPipeName(viewId);
+	return path.join(viewDir(root, viewId), "control.sock");
+}
 /** @param {string} root @param {string} viewId */
-export const controlSocketPath = (root, viewId) => path.join(viewDir(root, viewId), "control.sock");
+export const controlSocketPath = (root, viewId) => controlSocketPathFor(process.platform, root, viewId);
 /** @param {string} root @param {string} viewId */
 export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId), "screen.log");
 /** @param {string} root @param {string} viewId */
@@ -65,6 +86,8 @@ export const diagnosticsPath = (root, viewId) => path.join(viewDir(root, viewId)
 /** @param {string} root @param {string} viewId */
 export const evidencePath = (root, viewId) => path.join(viewDir(root, viewId), "evidence.json");
 /** @param {string} root @param {string} viewId */
+export const codeRefsPath = (root, viewId) => path.join(viewDir(root, viewId), "github.json");
+/** @param {string} root @param {string} viewId */
 export const viewEvidencePath = evidencePath;
 /** @param {string} root @param {string} viewId */
 export const followUpQueuePath = (root, viewId) => path.join(viewDir(root, viewId), "queue.json");

package/src/core/pty-attach-reconnect.mjs

@@ -0,0 +1,43 @@
+/**
+ * Attach reconnect policy (issue #48). The pty-runner can die without sending
+ * an exit message (uncaught crash), which previously left the attach view in a
+ * 150 ms reconnect loop forever with no way out. Two regimes:
+ *  - ever connected: a crashed host is unrecoverable quickly — give up after a
+ *    short window and report "host exited";
+ *  - never connected: the host may still be cold-starting (service launches it
+ *    right before attach) — allow a long window before declaring it unreachable.
+ */
+
+/** Give-up delay after a previously-established connection drops (ms). */
+export const ATTACH_RECONNECT_TIMEOUT_MS = 15_000;
+/** Give-up delay while waiting for the initial host connection (ms). */
+export const ATTACH_HOST_START_TIMEOUT_MS = 120_000;
+
+/**
+ * @param {{ everConnected: boolean, disconnectedAt: number|null, connectStartedAt: number, now: number }} input
+ * @returns {{ giveUp: boolean, status: string | null }}
+ */
+export function evaluateAttachReconnect({ everConnected, disconnectedAt, connectStartedAt, now }) {
+	if (everConnected && disconnectedAt !== null) {
+		const elapsed = now - disconnectedAt;
+		return elapsed >= ATTACH_RECONNECT_TIMEOUT_MS
+			? { giveUp: true, status: "host exited" }
+			: { giveUp: false, status: null };
+	}
+	const elapsed = now - connectStartedAt;
+	return elapsed >= ATTACH_HOST_START_TIMEOUT_MS
+		? { giveUp: true, status: "host not reachable" }
+		: { giveUp: false, status: null };
+}
+
+/**
+ * Detach-key policy: while the socket is down a key can never reach the child,
+ * so treat ← / ctrl+] as "leave the view" unconditionally; otherwise keep the
+ * existing empty-input-line gate (issue #48 comment 1).
+ * @param {boolean} connected
+ * @param {boolean} childInputLooksEmpty
+ * @returns {boolean}
+ */
+export function shouldEscapeAttach(connected, childInputLooksEmpty) {
+	return !connected || childInputLooksEmpty;
+}

package/src/core/repo.mjs

@@ -1,5 +1,6 @@
 /** Git repository identity. Pure node (shells out to `git`); returns null off-repo. */
 import { execFileSync } from "node:child_process";
+import { parseRemoteHost } from "./code-refs.mjs";
 
 /**
  * Resolve the git repo root containing `cwd`, or null if not in a repo.
@@ -45,3 +46,55 @@ export function isDirty(repoRoot) {
 		return false;
 	}
 }
+
+/**
+ * Cached origin-remote URL per repo root. Failures are cached as null so each
+ * repo root is only ever queried once per process.
+ * @type {Map<string, string|null>}
+ */
+const remoteUrlCache = new Map();
+
+/**
+ * Raw URL of the `origin` remote of `repoRoot`, or null when the repo has no
+ * origin remote or is not a repo. The result (including misses) is cached per
+ * repoRoot.
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+export function gitRemoteUrl(repoRoot) {
+	const cached = remoteUrlCache.get(repoRoot);
+	if (cached !== undefined) return cached;
+	let url = null;
+	try {
+		const out = execFileSync("git", ["-C", repoRoot, "remote", "get-url", "origin"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 2000,
+		});
+		url = out.trim() || null;
+	} catch {
+		// not a repo or no origin remote
+	}
+	remoteUrlCache.set(repoRoot, url);
+	return url;
+}
+
+/**
+ * Host of the `origin` remote of `repoRoot`, lowercased and without port, or
+ * null when the repo has no origin remote or is not a repo. Supports
+ * `https://host/owner/repo(.git)` and `git@host:owner/repo(.git)`; parsed from
+ * the cached raw remote URL.
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+export function gitRemoteHost(repoRoot) {
+	return parseRemoteHost(gitRemoteUrl(repoRoot));
+}
+
+/**
+ * Clear the gitRemoteHost cache. Test-only helper.
+ * @returns {void}
+ */
+export function clearRemoteHostCacheForTests() {
+	remoteUrlCache.clear();
+}

package/src/core/rows.mjs

@@ -10,6 +10,13 @@ import { GROUP_LABELS, GROUP_ORDER, SEMANTIC_STATES } from "./types.mjs";
 /** @typedef {import("./store.mjs").Row} Row */
 /** @typedef {import("./types.mjs").SemanticState} SemanticState */
 
+/**
+ * Host heartbeat staleness threshold (ms). The pty-runner writes host.json on a
+ * 1 Hz heartbeat; when a crashed runner leaves host.json stuck on "alive", the
+ * heartbeat goes stale within seconds (issue #48 L4).
+ */
+const STALE_HOST_MS = 10_000;
+
 /**
  * @typedef {Object} RowView
  * @property {string} id
@@ -24,6 +31,8 @@ import { GROUP_LABELS, GROUP_ORDER, SEMANTIC_STATES } from "./types.mjs";
  * @property {SemanticState} state
  * @property {boolean} alive
  * @property {boolean} hostAlive
+ * @property {boolean} staleHost True when host.json claims alive but the runner
+ *   process is gone and the heartbeat is stale (display-only crash marker).
  * @property {boolean} needsInput
  * @property {boolean} hasError
  * @property {boolean} worktree
@@ -35,6 +44,9 @@ import { GROUP_LABELS, GROUP_ORDER, SEMANTIC_STATES } from "./types.mjs";
  * @property {number} followUpCount
  * @property {string|null} followUpPreview
  * @property {string} steeringState
+ * @property {string} refsBadge Inline issue/PR badge (e.g. "#40 ▸#45"); "" when there are no refs.
+ * @property {boolean} refsLowConfidence True when the winning issue or pr confidence is "low".
+ * @property {import("./types.mjs").CodeRefsSummary|null} codeRefs Compact ref summary the peek view consumes.
  * @property {number} lastActivityAt
  * @property {number} createdAt
  */
@@ -115,6 +127,19 @@ export function rowView(row, now) {
 	const place = folderName;
 	const lastVisitedAt = row.state?.lastVisitedAt ?? null;
 	const lastAgentActivityAt = row.state?.lastAgentActivityAt ?? null;
+	const refs = codeRefsBadge(row.codeRefs);
+	// Host-lost display marker (issue #48 L4): host.json still claims "alive"
+	// but the runner process is gone and the 1 Hz heartbeat went stale — the
+	// crash path leaves exactly this fingerprint (no exit message, no
+	// reconcile). Display-only; state.json is deliberately untouched.
+	const host = row.host;
+	const staleHost = Boolean(
+		host &&
+			host.state === "alive" &&
+			!row.hostAlive &&
+			typeof host.lastSeenAt === "number" &&
+			now - host.lastSeenAt > STALE_HOST_MS,
+	);
 	return {
 		id: row.meta.id,
 		name: row.meta.name,
@@ -128,6 +153,7 @@ export function rowView(row, now) {
 		state,
 		alive: Boolean(row.alive),
 		hostAlive: Boolean(row.hostAlive),
+		staleHost,
 		needsInput: state === "needs_input",
 		hasError: state === "failed",
 		worktree,
@@ -139,11 +165,35 @@ export function rowView(row, now) {
 		followUpCount: row.state?.followUps?.queuedCount ?? 0,
 		followUpPreview: row.state?.followUps?.lastQueuedPreview ?? null,
 		steeringState: row.state?.steering?.status ?? "none",
+		refsBadge: refs.refsBadge,
+		refsLowConfidence: refs.refsLowConfidence,
+		codeRefs: row.codeRefs ?? null,
 		lastActivityAt,
 		createdAt: row.meta.createdAt ?? 0,
 	};
 }
 
+/**
+ * Map a CodeRefsSummary to the inline badge strings shown on dashboard rows:
+ * the winning issue and pr joined by a space, each prefixed with the provider
+ * prefix stored on the summary; plus the low-confidence flag that makes the
+ * dashboard dim the badge. Missing/garbage summaries yield an empty badge.
+ * @param {import("./types.mjs").CodeRefsSummary|null|undefined} summary
+ * @returns {{ refsBadge: string, refsLowConfidence: boolean }}
+ */
+function codeRefsBadge(summary) {
+	if (!summary) return { refsBadge: "", refsLowConfidence: false };
+	const issue = summary.issue;
+	const pr = summary.pr;
+	const parts = [];
+	if (issue && Number.isFinite(issue.number)) parts.push(`${summary.issuePrefix ?? "#"}${issue.number}`);
+	if (pr && Number.isFinite(pr.number)) parts.push(`${summary.prPrefix ?? "▸#"}${pr.number}`);
+	return {
+		refsBadge: parts.join(" "),
+		refsLowConfidence: issue?.confidence === "low" || pr?.confidence === "low",
+	};
+}
+
 /** @param {string} text */
 function oneLine(text) {
 	return String(text || "").replace(/\s+/g, " ").trim() || "—";

package/src/core/store.mjs

@@ -7,6 +7,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { atomicWriteJson, ensureDir, readJson } from "./atomic.mjs";
 import * as P from "./paths.mjs";
 import { isAlive } from "./pid.mjs";
+import { readCodeRefs, summarizeCodeRefs } from "./code-refs-store.mjs";
 import { readDiagnosticSummary } from "./diagnostics.mjs";
 import { readEvidence, summarizeEvidence } from "./evidence.mjs";
 import { readFollowUpQueue, summarizeFollowUpQueue } from "./follow-up-queue.mjs";
@@ -181,6 +182,7 @@ function mtime(dir) {
  * @property {import("./types.mjs").DiagnosticSummary} [diagnostics]
  * @property {import("./types.mjs").FollowUpSummary} [followUps]
  * @property {import("./types.mjs").SteeringSummary} [steering]
+ * @property {import("./types.mjs").CodeRefsSummary} [codeRefs]
  */
 
 /** @param {string} root @param {string} viewId @returns {Row|null} */
@@ -211,7 +213,8 @@ export function readViewArtifactSummaries(root, viewId) {
 	const diagnostics = readDiagnosticSummary(root, viewId);
 	const followUps = summarizeFollowUpQueue(readFollowUpQueue(root, viewId));
 	const steering = summarizeSteering(readSteering(root, viewId));
-	return { review, diagnostics, followUps, steering };
+	const codeRefs = summarizeCodeRefs(readCodeRefs(root, viewId));
+	return { review, diagnostics, followUps, steering, codeRefs };
 }
 
 /**

package/src/core/types.mjs

@@ -118,6 +118,7 @@ export const GROUP_LABELS = {
  * @property {DiagnosticSummary} [diagnostics] Compact diagnostics summary.
  * @property {FollowUpSummary} [followUps] Compact queued follow-up summary.
  * @property {SteeringSummary} [steering] Compact plan/approval steering summary.
+ * @property {CodeRefsSummary} [codeRefs] Compact issue/PR reference summary.
  * @property {AutoStateClassification|null} [autoState] Latest automatic terminal-state classification.
  */
 
@@ -364,6 +365,17 @@ export const GROUP_LABELS = {
 
 /** @typedef {{ status:SteeringModeState, awaitingApproval:boolean, planPreview:string|null, updatedAt:number|null, question:string|null }} SteeringSummary */
 
+/**
+ * Compact issue/PR reference summary for a view (`github.json`).
+ * @typedef {Object} CodeRefsSummary
+ * @property {string|null} provider Resolved provider name (e.g. "github"); always non-null after a successful extraction (falls back to "generic"), null only before any extraction has run.
+ * @property {string} issuePrefix Issue-number prefix resolved from the matched provider at write time (default "#").
+ * @property {string} prPrefix PR/MR-number prefix resolved from the matched provider at write time (default "▸#"; "!" for gitlab).
+ * @property {import("./code-refs.mjs").Ref|null} issue
+ * @property {import("./code-refs.mjs").Ref|null} pr
+ * @property {import("./code-refs.mjs").Ref[]} allRefs Distinct refs for the peek view (max 10).
+ */
+
 /** Roster index (`roster.json`). @typedef {Object} Roster @property {number} version @property {string[]} views */
 
 /**

package/src/runtime/service.mjs

@@ -13,6 +13,7 @@ import { appendLine } from "../core/atomic.mjs";
 import { finalizeRun, projectViewState, reduceEvent } from "../core/events.mjs";
 import { clearDiagnostics, appendDiagnostic, tailDiagnostics } from "../core/diagnostics.mjs";
 import { emptyEvidenceSnapshot, finalizeEvidence, readEvidence, reduceEvidence, summarizeEvidence, writeEvidence } from "../core/evidence.mjs";
+import { updateCodeRefsFromEvidence } from "../core/code-refs-store.mjs";
 import { claimNextFollowUp, completeFollowUp, enqueueFollowUp, readFollowUpQueue, releaseFollowUp, summarizeFollowUpQueue, clearQueuedFollowUps, removeLastFollowUp } from "../core/follow-up-queue.mjs";
 import { approvePlan as approvePlanState, markExecutingApprovedPlan, readSteering, recordPlanReady, requestPlan as requestPlanState, requestPlanChanges as requestPlanChangesState, summarizeSteering } from "../core/steering.mjs";
 import { buildApprovePlanPrompt, buildPlanChangesPrompt, buildPlanRequestPrompt } from "../core/steering-prompts.mjs";
@@ -517,6 +518,7 @@ export function createService(opts) {
 		try {
 			reduceEvidence(evidence, event, now);
 			writeEvidence(root, evidence);
+			updateCodeRefsFromEvidence(root, row.meta.id, evidence, row.meta);
 		} catch (err) {
 			appendDiagnostic(root, row.meta.id, { source: "evidence", level: "warn", code: "evidence_reduce_failed", message: "Could not reduce hosted evidence", details: { error: err instanceof Error ? err.message : String(err) } });
 		}
@@ -548,6 +550,7 @@ export function createService(opts) {
 			}
 			status.evidenceSummary = summarizeEvidence(evidence);
 			writeEvidence(root, evidence);
+			updateCodeRefsFromEvidence(root, row.meta.id, evidence, row.meta);
 			writeForegroundState(row, status);
 			pruneWarmHosts({ keepViewId: row.meta.id });
 			drainNextFollowUp(row.meta.id);
@@ -1142,7 +1145,10 @@ function compactSummary(text) {
 function sendHostMessage(row, message) {
 	const socketPath = row.host?.socketPath;
 	if (!socketPath) return { ok: false, error: "No host socket" };
-	if (!existsSync(socketPath)) return { ok: false, error: "Host socket is not ready" };
+	// On Windows the control socket is a named pipe, which never exists as a
+	// filesystem entry, so existsSync can't be used as a readiness probe there.
+	// A missing pipe surfaces as a connection error on the socket below.
+	if (process.platform !== "win32" && !existsSync(socketPath)) return { ok: false, error: "Host socket is not ready" };
 	try {
 		const socket = createConnection(socketPath);
 		socket.on("connect", () => {

package/src/ui/dashboard.ts

@@ -1362,8 +1362,9 @@ export class DashboardComponent implements Component {
 		const contentWidth = Math.max(20, width - indent);
 		const glyph = stateGlyph(rv.state, rv.alive, rv.hostAlive, rv.unread);
 		const marker = stageFg(rv.state, selected ? `›${glyph}` : ` ${glyph}`);
-		const statusBadges = `${rv.reviewReady ? "✓ " : ""}${rv.diagnosticStalled ? "⏳ " : ""}${rv.evidenceErrorCount || rv.diagnosticErrorCount ? "! " : ""}${rv.followUpCount ? `q${rv.followUpCount} ` : ""}${rv.steeringState && rv.steeringState !== "none" ? "π " : ""}`;
-		const badge = `${this.mode === "select" ? `${this.isSelectedForBatch(rv.id) ? "◉" : "○"} ` : ""}${rv.pinned ? "★ " : ""}${rv.worktree ? "⌥ " : ""}${statusBadges}`;
+		const statusBadges = `${rv.reviewReady ? "✓ " : ""}${rv.diagnosticStalled ? "⏳ " : ""}${rv.staleHost ? "⌁ " : ""}${rv.evidenceErrorCount || rv.diagnosticErrorCount ? "! " : ""}${rv.followUpCount ? `q${rv.followUpCount} ` : ""}${rv.steeringState && rv.steeringState !== "none" ? "π " : ""}`;
+		const refsBadge = rv.refsBadge ? (rv.refsLowConfidence ? t.fg("dim", rv.refsBadge) : rv.refsBadge) : "";
+		const badge = `${this.mode === "select" ? `${this.isSelectedForBatch(rv.id) ? "◉" : "○"} ` : ""}${rv.pinned ? "★ " : ""}${rv.worktree ? "⌥ " : ""}${statusBadges}${refsBadge ? `${refsBadge} ` : ""}`;
 		const ageRaw = ` ${rv.age}`;
 		const nameW = clamp(Math.floor(contentWidth * 0.34), 18, 30);
 		const folderW = opts.showFolder !== false ? (contentWidth >= 72 ? clamp(Math.floor(contentWidth * 0.16), 10, 22) : contentWidth >= 56 ? 10 : 0) : 0;
@@ -1396,6 +1397,17 @@ export class DashboardComponent implements Component {
 			out.push(t.fg("muted", "Auto-state"));
 			out.push(clip(`  ${auto.kind} · ${auto.confidence} · ${auto.source}${auto.reason ? ` — ${auto.reason}` : ""}`, width));
 		}
+		if (row.codeRefs && row.codeRefs.allRefs.length > 0) {
+			const codeRefs = row.codeRefs;
+			out.push("");
+			out.push(t.fg("muted", "Refs"));
+			if (codeRefs.provider) out.push(clip(`  ${codeRefs.provider}`, width));
+			for (const ref of codeRefs.allRefs) {
+				const prefix = ref.kind === "pr" ? (codeRefs.prPrefix ?? "▸#") : (codeRefs.issuePrefix ?? "#");
+				const line = `  ${ref.kind} ${prefix}${ref.number} · ${ref.confidence} · ${ref.source}${ref.url ? ` · ${ref.url}` : ""}`;
+				out.push(clip(line, width));
+			}
+		}
 		if (row.state?.question) {
 			out.push("");
 			out.push(t.fg("warning", "Question / blocker"));