@zhuxixi/pi-agent-board 0.5.2 → 0.6.0

package/src/core/code-refs.mjs

@@ -506,12 +506,55 @@ const REF_CONFIDENCE = { claim: "high", action: "high", view: "medium", mention:
 
 /** URL rules carry a `/issues/`, `/pull/`, or `/merge_requests/` path segment. */
 const URL_RULE_RE = /issues\/|pull\/|merge_requests\//;
-/** `closes #N` / `fixes #N` / `issue #N` back-link inside a `pr create` body. */
-const PR_BACKLINK_RE = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|issue)\s+#(\d{1,7})/i;
+/**
+ * Back-link inside an explicit `pr create` command body: closing keywords
+ * (optionally followed by "issue") or the legacy bare `issue #N` form.
+ * Word boundaries keep embedded keywords (prefix/disclose/unresolved) out;
+ * `(?!\w)` rejects longer numbers instead of truncating them to 7 digits.
+ */
+const PR_CREATE_BACKLINK_RE =
+	/\b(?:(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b\s+(?:issue\s+)?|issue\s+)#(\d{1,7})(?!\w)/i;
+/**
+ * Back-link in later assistant evidence: canonical closing-keyword syntax
+ * only (`closes #N` etc.). A bare `issue #N` mention — e.g. a code-review
+ * report's finding number — never matches here (issue #65).
+ */
+const PR_FOLLOWUP_BACKLINK_RE =
+	/\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b\s+#(\d{1,7})(?!\w)/i;
+
+/**
+ * Match a PR→issue back-link in the text of an explicit `pr create` command
+ * (closing keywords or the legacy bare `issue #N` body form).
+ * @param {string} text
+ * @returns {number|null}
+ */
+function matchPrCreateBacklink(text) {
+	const m = PR_CREATE_BACKLINK_RE.exec(text);
+	return m ? Number(m[1]) : null;
+}
+
+/**
+ * Match a PR→issue back-link in later assistant evidence — canonical
+ * closing-keyword syntax only, never a bare `issue #N` (issue #65).
+ * @param {string} text
+ * @returns {number|null}
+ */
+function matchPrFollowupBacklink(text) {
+	const m = PR_FOLLOWUP_BACKLINK_RE.exec(text);
+	return m ? Number(m[1]) : null;
+}
 /** `issue-<N>-...` worktree/branch naming convention (engine-builtin). */
 const WORKTREE_RE = /(?:^|[/\\])issue-(\d{1,7})(?:-|$)/;
-/** Bare `#N` mentions. */
-const MENTION_RE = /#(\d{1,7})/g;
+/**
+ * Bare `#N` mentions. The lookbehind rejects a preceding `#` (markdown
+ * headings, `##N` typos) or word character (`a#1`) — those are not issue
+ * references (issue #61).
+ */
+const MENTION_RE = /(?<![#\w])#(\d{1,7})/g;
+/** Inline code span (single-line) — excluded from mention counting. */
+const INLINE_CODE_SPAN_RE = /`[^`\n]*`/g;
+/** Explicit PR-context tokens immediately before a `#N` match. */
+const PR_CONTEXT_RE = /(?:^|\W)(?:pr|pull|mr|merge)s?(?:\W|$)/i;
 
 /** Worktree/branch naming is session metadata, treated as before the transcript. */
 const WORKTREE_INDEX = -1;
@@ -588,23 +631,25 @@ export function extractCodeRefs(input, provider) {
 	});
 
 	// Rule 3: resolve pending create markers against subsequent evidence.
-	for (let mi = 0; mi < pendingCreates.length; mi++) {
-		const marker = pendingCreates[mi];
+	for (const marker of pendingCreates) {
 		const resolved = resolveCreate(marker, commands, assistantTexts, urlRules);
 		if (resolved) {
 			addCandidate(candidates, marker.kind, resolved.number, "action", "create-url", resolved.index);
 		}
-		// Rule 4b: the issue back-link of a created PR may live in a later
-		// assistant message ("This PR closes #40") or in --body-file content
-		// that never appears in the command string — scan subsequent evidence
-		// for the back-link pattern as well (not just the command itself).
-		// The scan stops at the NEXT pr-create marker so an earlier create
-		// never absorbs a later PR's back-link.
-		if (marker.kind === "pr") {
-			const nextPr = pendingCreates.slice(mi + 1).find((m) => m.kind === "pr");
-			const backlink = resolveBacklinkAfter(marker, commands, assistantTexts, nextPr?.index ?? Infinity);
-			if (backlink) addCandidate(candidates, "issue", backlink.number, "claim", "pr-backlink", backlink.index);
-		}
+	}
+	// Rule 4b: the issue back-link of a created PR may live in a later
+	// assistant message ("This PR closes #40") or in --body-file content that
+	// never appears in the command string. The flattened evidence input keeps
+	// no interleaving timestamps, so a follow-up back-link can be attributed
+	// only when exactly one distinct PR-create command exists; with zero or
+	// multiple PR creates the assistant scan is skipped rather than guessing.
+	// Later commands are never scanned: `gh issue close #N` or
+	// `gh pr comment ... fixes #N` are their own signals, not this PR's
+	// back-link (issue #65).
+	const prCreateIndexes = new Set(pendingCreates.filter((m) => m.kind === "pr").map((m) => m.index));
+	if (prCreateIndexes.size === 1) {
+		const backlink = resolveBacklinkAfter(assistantTexts, commands.length);
+		if (backlink) addCandidate(candidates, "issue", backlink.number, "claim", "pr-backlink", backlink.index);
 	}
 
 	// Rule 5: worktree/branch naming (engine-builtin, not configurable).
@@ -635,26 +680,26 @@ export function extractCodeRefs(input, provider) {
  * @param {Array<{kind: "issue"|"pr", number: number, strength: string, source: string, lastIndex: number}>} candidates
  */
 function applyPrBacklink(text, index, candidates) {
-	const m = PR_BACKLINK_RE.exec(text);
-	if (m) addCandidate(candidates, "issue", Number(m[1]), "claim", "pr-body", index);
+	const number = matchPrCreateBacklink(text);
+	if (number !== null) addCandidate(candidates, "issue", number, "claim", "pr-body", index);
 }
 
 /**
- * Find the first PR→issue back-link ("Closes #N" etc.) in evidence AFTER a
- * `pr create` marker — covers assistant messages and later commands alike.
- * The scan stops before `stopBefore` (typically the next pr-create marker).
- * @param {{kind: "issue"|"pr", index: number}} marker
- * @param {Array<{command: string}>} commands
+ * Find the first PR→issue back-link in later assistant texts — canonical
+ * closing-keyword syntax only ("Closes #N" etc., see
+ * PR_FOLLOWUP_BACKLINK_RE). Commands are never scanned. `baseIndex` (the
+ * command count) keeps the existing ordering contract; it is not a real
+ * timestamp.
  * @param {string[]} assistantTexts
- * @param {number} [stopBefore]
+ * @param {number} baseIndex
+ * @returns {{number: number, index: number}|null}
  */
-function resolveBacklinkAfter(marker, commands, assistantTexts, stopBefore = Infinity) {
-	const total = Math.min(commands.length + assistantTexts.length, stopBefore);
-	for (let index = marker.index + 1; index < total; index++) {
-		const text = evidenceTextAt(index, commands, assistantTexts);
-		if (!text) continue;
-		const m = PR_BACKLINK_RE.exec(text);
-		if (m) return { number: Number(m[1]), index };
+function resolveBacklinkAfter(assistantTexts, baseIndex) {
+	for (let i = 0; i < assistantTexts.length; i++) {
+		const text = assistantTexts[i];
+		if (typeof text !== "string" || !text) continue;
+		const number = matchPrFollowupBacklink(text);
+		if (number !== null) return { number, index: baseIndex + i };
 	}
 	return null;
 }
@@ -734,7 +779,14 @@ function mentionFallback(assistantTexts, baseIndex) {
 	for (let i = start; i < assistantTexts.length; i++) {
 		const text = assistantTexts[i];
 		if (typeof text !== "string") continue;
-		for (const m of text.matchAll(MENTION_RE)) {
+		// Doc examples inside inline code spans are not real references; strip
+		// them before counting (issue #61).
+		const stripped = text.replace(INLINE_CODE_SPAN_RE, " ");
+		for (const m of stripped.matchAll(MENTION_RE)) {
+			// `monitor pr #N` is explicitly PR context: do not count it toward
+			// the issue fallback (issue #61).
+			const before = stripped.slice(Math.max(0, m.index - 16), m.index);
+			if (PR_CONTEXT_RE.test(before)) continue;
 			const n = Number(m[1]);
 			counts.set(n, (counts.get(n) ?? 0) + 1);
 			lastIndex.set(n, baseIndex + i);

package/src/core/evidence.mjs

@@ -1,5 +1,5 @@
 /** Review evidence extraction and persistence helpers. */
-import { assistantText, classifyCommand, toolFileOperation, truncate } from "./heuristics.mjs";
+import { assistantText, classifyCommand, toolFileOperation, toolResultText, truncate } from "./heuristics.mjs";
 import { atomicWriteJson, readJson } from "./atomic.mjs";
 import * as P from "./paths.mjs";
 
@@ -195,7 +195,7 @@ export function reduceEvidence(snapshot, event, now = Date.now()) {
 				command: event.args?.command ?? "",
 				status: event.isError ? "failed" : "passed",
 				exitCode: event.isError ? 1 : 0,
-				outputPreview: truncate(String(event.result ?? ""), 500),
+				outputPreview: truncate(toolResultText(event.result), 500),
 			});
 			changed = true;
 		}

package/src/core/heuristics.mjs

@@ -22,6 +22,27 @@ export function assistantText(message) {
 		.trim();
 }
 
+/**
+ * Extract text from a pi AgentToolResult object
+ * ({ content: [{ type: "text", text }, ...], details, ... }), or, defensively,
+ * a plain string. Unknown-shaped objects yield "" — never "[object Object]"
+ * (issue #41; mirrors pi's own convertToolResultOutput join("\n") semantics).
+ * @param {any} result
+ * @returns {string}
+ */
+export function toolResultText(result) {
+	if (result == null) return "";
+	if (typeof result === "string") return result;
+	if (typeof result !== "object") return String(result);
+	const content = result.content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((b) => b && b.type === "text" && typeof b.text === "string")
+		.map((b) => b.text)
+		.join("\n")
+		.trim();
+}
+
 /**
  * Collect tool-call blocks from an assistant message.
  * @param {any} message
@@ -209,16 +230,33 @@ function capitalize(s) {
 	return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
 }
 
+const LONE_HIGH_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g;
+const LONE_LOW_SURROGATE_RE = /(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+/** @param {string} s */
+function stripLoneSurrogates(s) {
+	if (!s) return s;
+	return s.replace(LONE_HIGH_SURROGATE_RE, "").replace(LONE_LOW_SURROGATE_RE, "");
+}
+
 /**
  * Truncate to `n` chars with an ellipsis (counts characters, not display width).
+ * The budget `n` is in UTF-16 units. The cut never splits a surrogate pair
+ * (it backs off one unit when it would), and lone surrogates in the input are
+ * stripped from the result — a lone surrogate renders as U+FFFD, whose
+ * terminal width can disagree with the computed width and misalign rows.
  * @param {string} s
  * @param {number} n
  * @returns {string}
  */
 export function truncate(s, n) {
 	const str = String(s ?? "");
-	if (str.length <= n) return str;
-	return `${str.slice(0, Math.max(0, n - 1))}…`;
+	if (str.length <= n) return stripLoneSurrogates(str);
+	let end = Math.max(0, n - 1);
+	const lastUnit = str.charCodeAt(end - 1);
+	const nextUnit = str.charCodeAt(end);
+	if (lastUnit >= 0xd800 && lastUnit <= 0xdbff && nextUnit >= 0xdc00 && nextUnit <= 0xdfff) end -= 1;
+	return `${stripLoneSurrogates(str.slice(0, end))}…`;
 }
 
 /**

package/src/core/host-coordination.mjs

@@ -0,0 +1,159 @@
+/**
+ * Pure host-lifecycle decision functions (issue #70).
+ *
+ * Every function here takes plain snapshots (HostStatus-shaped objects, probe
+ * results, process observations) and returns a decision — no fs/net/process
+ * I/O. Callers (locks, store, service, runner) own all side effects; this
+ * module is the single source of truth for the coordination rules so they can
+ * be unit-tested exhaustively.
+ *
+ * @typedef {import("./types.mjs").HostStatus} HostStatus
+ */
+
+/**
+ * Whether `host` is owned by the given fencing token. A null/missing
+ * instanceId never matches — legacy hosts have no owner token.
+ * @param {HostStatus|null|undefined} host
+ * @param {string|null|undefined} expectedInstanceId
+ * @returns {boolean}
+ */
+export function sameHostOwner(host, expectedInstanceId) {
+	if (!host || !expectedInstanceId) return false;
+	return host.instanceId === expectedInstanceId;
+}
+
+/**
+ * Whether a `starting` claim is still inside the launch grace window.
+ * A missing runnerPid or socket does NOT make a fresh claim stale (issue #70:
+ * provisional claims are normal while the runner boots).
+ * @param {HostStatus|null|undefined} host
+ * @param {number} now Epoch ms.
+ * @param {number} graceMs
+ * @returns {boolean}
+ */
+export function isStartingWithinGrace(host, now, graceMs) {
+	if (!host || host.state !== "starting" || host.claimAt == null) return false;
+	return now - host.claimAt < graceMs;
+}
+
+/**
+ * Classify a recorded process identity against a live observation.
+ * Five states — `not_started` (never spawned) must never be conflated with
+ * `dead`, and a missing stable token must never be guessed as alive-owned:
+ * it degrades to `unknown` so recovery can only refuse, never misfire.
+ * @param {{pid:number,startToken:string|null}|null|undefined} identity The recorded identity.
+ * @param {{alive:boolean,startToken:string|null}|null|undefined} observed The observation.
+ * @param {number|null|undefined} spawnedAt Non-null only after spawn was confirmed.
+ * @returns {"not_started"|"dead"|"owned"|"foreign"|"unknown"}
+ */
+export function processIdentityState(identity, observed, spawnedAt) {
+	if (spawnedAt == null) return "not_started";
+	if (observed?.alive === false) return "dead";
+	if (identity?.startToken == null || observed?.startToken == null) return "unknown";
+	return identity.startToken === observed.startToken ? "owned" : "foreign";
+}
+
+/** Role observations that mean "no live process can belong to the old instance". */
+const SAFE_TO_RELEASE = new Set(["not_started", "dead", "foreign"]);
+
+/**
+ * Whether an exited/failed host can be replaced by a new claim. Every role
+ * (runner, child, provisional-claim launcher) must be provably gone; any
+ * `unknown` observation or an active launch lease blocks replacement.
+ * @param {{
+ *   host: HostStatus|null|undefined,
+ *   runnerObservation: string,
+ *   childObservation: string,
+ *   claimObservation: string,
+ *   launchLeaseActive: boolean,
+ * }} input
+ * @returns {boolean}
+ */
+export function canReplaceHost({ host, runnerObservation, childObservation, claimObservation, launchLeaseActive }) {
+	if (!host || (host.state !== "exited" && host.state !== "failed")) return false;
+	if (launchLeaseActive) return false;
+	return (
+		SAFE_TO_RELEASE.has(runnerObservation) &&
+		SAFE_TO_RELEASE.has(childObservation) &&
+		SAFE_TO_RELEASE.has(claimObservation)
+	);
+}
+
+/**
+ * Whether the endpoint file at `current` is the one this instance bound.
+ * Compares dev+ino so a replaced (rebound) socket path is never unlinked by
+ * its former owner.
+ * @param {{dev:number,ino:number}|null|undefined} bound Identity recorded at bind time.
+ * @param {{dev:number,ino:number}|null|undefined} current Identity observed at cleanup time.
+ * @returns {boolean}
+ */
+export function ownsEndpoint(bound, current) {
+	return Boolean(bound && current && bound.dev === current.dev && bound.ino === current.ino);
+}
+
+/**
+ * Classify a connect+hello probe snapshot into the coordination enum.
+ * Order: connection errors first (they carry the errorCode), then protocol
+ * validity, then ownership mismatch (`occupied` — never touch), then
+ * readiness. A valid matching host that is not ready yet is `starting`, which
+ * callers treat as "wait", never as stale.
+ * @param {{
+ *   connected?: boolean,
+ *   protocolValid?: boolean,
+ *   viewMatch?: boolean,
+ *   instanceMatch?: boolean,
+ *   state?: string|null,
+ *   readyAt?: number|null,
+ *   errorCode?: string|null,
+ *   isSocket?: boolean,
+ * }} result Probe snapshot from host-probe.
+ * @returns {"ready"|"starting"|"stale"|"occupied"|"missing"|"unknown"}
+ */
+export function classifyProbeResult(result) {
+	if (!result) return "unknown";
+	if (!result.connected) {
+		if (result.errorCode === "ENOENT") return "missing";
+		if (result.errorCode === "ECONNREFUSED" && result.isSocket) return "stale";
+		return "unknown";
+	}
+	if (!result.protocolValid) return "unknown";
+	if (result.viewMatch === false || result.instanceMatch === false) return "occupied";
+	if (result.state === "alive" && result.readyAt != null) return "ready";
+	return "starting";
+}
+
+/** Host states in which a claim exists and must not be duplicated. */
+const ACTIVE_STATES = new Set(["starting", "alive", "stopping"]);
+
+/**
+ * Whether a runner starting for `instanceId` must yield because the host
+ * record belongs to another still-active instance.
+ * @param {{host: HostStatus|null|undefined, instanceId: string|null|undefined}} input
+ * @returns {boolean}
+ */
+export function shouldYieldRunner({ host, instanceId }) {
+	if (!host || host.instanceId === instanceId) return false;
+	return ACTIVE_STATES.has(host.state);
+}
+
+/**
+ * Whether a host is ready to accept service-generated input: alive, ready,
+ * and not revoked.
+ * @param {HostStatus|null|undefined} host
+ * @returns {boolean}
+ */
+export function shouldAcceptInput(host) {
+	if (!host || host.state !== "alive" || host.readyAt == null) return false;
+	return host.stopRequestedAt == null;
+}
+
+/**
+ * Whether a failed `listen` with this error may be retried (only EADDRINUSE,
+ * only the single configured retry).
+ * @param {string|null|undefined} errorCode
+ * @param {number} attempt Zero-based retry attempt already made.
+ * @returns {boolean}
+ */
+export function shouldRetryBind(errorCode, attempt) {
+	return errorCode === "EADDRINUSE" && attempt < 1;
+}

package/src/core/host-crash.mjs

@@ -4,16 +4,22 @@
  * Never throws — this runs on the crash path.
  */
 import { appendDiagnostic } from "./diagnostics.mjs";
-import { writeHost } from "./store.mjs";
+import { updateOwnedHost, writeHost } from "./store.mjs";
 
 /**
  * @param {string} root
  * @param {string} viewId
  * @param {object|null} host
  * @param {unknown} error
+ * @param {{ expectedInstanceId?: string|null }} [opts] When `expectedInstanceId`
+ *   is set (new ownership protocol, issue #70), the failed state is written via
+ *   the owner-fenced `updateOwnedHost` — a superseded instance can never
+ *   clobber the replacement's live record; the skip is recorded as a
+ *   `host_crash_owner_changed` diagnostic. Without it the legacy wholesale
+ *   `writeHost` behavior is preserved exactly.
  * @returns {object}
  */
-export function finalizeHostCrash(root, viewId, host, error) {
+export function finalizeHostCrash(root, viewId, host, error, opts = {}) {
 	const message = error instanceof Error ? error.message : String(error);
 	const failed = {
 		...(host ?? { version: 1, viewId, mode: "pty", socketPath: null, startedAt: Date.now() }),
@@ -23,9 +29,44 @@ export function finalizeHostCrash(root, viewId, host, error) {
 		exitCode: 1,
 		error: message,
 	};
+	if (opts.expectedInstanceId != null) {
+		try {
+			// Build the terminal state from the LIVE record inside the host-meta
+			// lock — never from the possibly-stale `host` snapshot.
+			const result = updateOwnedHost(root, viewId, opts.expectedInstanceId, (cur) => ({
+				...cur,
+				state: "failed",
+				endedAt: Date.now(),
+				lastSeenAt: Date.now(),
+				exitCode: 1,
+				error: message,
+			}));
+			if (result.updated && result.host) {
+				appendCrashDiagnostic(root, viewId, message);
+				return result.host;
+			}
+			// ownerChanged, or the meta lock was briefly busy: never write unfenced.
+			try {
+				appendDiagnostic(root, viewId, {
+					source: "runner",
+					level: "warn",
+					code: "host_crash_owner_changed",
+					message: `Skipped crash finalize: host record no longer belongs to this instance (${message})`,
+					details: { error: message, ownerChanged: result.ownerChanged },
+				});
+			} catch { /* best effort */ }
+		} catch { /* best effort */ }
+		return failed;
+	}
 	try {
 		writeHost(root, failed);
 	} catch { /* best effort */ }
+	appendCrashDiagnostic(root, viewId, message);
+	return failed;
+}
+
+/** @param {string} root @param {string} viewId @param {string} message */
+function appendCrashDiagnostic(root, viewId, message) {
 	try {
 		appendDiagnostic(root, viewId, {
 			source: "runner",
@@ -35,5 +76,4 @@ export function finalizeHostCrash(root, viewId, host, error) {
 			details: { error: message },
 		});
 	} catch { /* best effort */ }
-	return failed;
 }

package/src/core/host-probe.mjs

@@ -0,0 +1,196 @@
+/**
+ * Real control-endpoint probe (issue #70).
+ *
+ * Connects to a PTY host control socket/pipe, performs the JSONL hello
+ * handshake, and classifies the outcome via `classifyProbeResult`. This is
+ * the ONLY "is this endpoint actually usable" authority — path existence and
+ * host.json state are hints, never proof (spec §7.1).
+ *
+ * Side-effectful by design (net + fs); all pure decisions live in
+ * host-coordination.mjs.
+ */
+import { createConnection } from "node:net";
+import { lstatSync } from "node:fs";
+import { classifyProbeResult } from "./host-coordination.mjs";
+
+/** Default probe timeout. */
+export const HOST_PROBE_TIMEOUT_MS = 250;
+/** Poll cadence between attach-resolver probes / retries (issue #70 Task 12). */
+export const HOST_PROBE_RETRY_MS = 150;
+
+/**
+ * @typedef {object} ProbeResult
+ * @property {"ready"|"starting"|"stale"|"occupied"|"missing"|"unknown"} classification
+ * @property {boolean} connected
+ * @property {boolean} protocolValid
+ * @property {boolean} ready
+ * @property {string|null} viewId
+ * @property {string|null} instanceId
+ * @property {string|null} state
+ * @property {string|null} errorCode
+ */
+
+/**
+ * Probe a host control endpoint via a real connection + JSONL hello.
+ *
+ * `connect` is injectable for tests; the default accepts anything
+ * `net.createConnection` accepts (a socket path / pipe name, or a
+ * `{ host, port }` address object) and must return a socket-like object with
+ * the usual `'connect' | 'data' | 'error'` events and a `.destroy()`.
+ *
+ * The probe socket is ALWAYS destroyed before the promise resolves.
+ *
+ * @param {string|{host:string,port:number}} socketPath
+ * @param {{ timeoutMs?: number, expectedViewId?: string|null, expectedInstanceId?: string|null, connect?: (target: any) => any }} [opts]
+ * @returns {Promise<ProbeResult>}
+ */
+export function probeHost(socketPath, opts = {}) {
+	const timeoutMs = opts.timeoutMs ?? HOST_PROBE_TIMEOUT_MS;
+	const expectedViewId = opts.expectedViewId ?? null;
+	const expectedInstanceId = opts.expectedInstanceId ?? null;
+	const connect = opts.connect ?? createConnection;
+
+	return new Promise((resolve) => {
+		/** @type {any} */ let socket;
+		/** @type {NodeJS.Timeout|null} */ let timer = null;
+		let settled = false;
+		let buffer = "";
+		/** @type {ProbeResult} */ let result;
+
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			try { socket?.destroy(); } catch { /* best effort */ }
+			resolve(result);
+		};
+
+		/** @param {string} errorCode */ const finishError = (errorCode) => {
+			const snapshot = {
+				connected: false,
+				protocolValid: false,
+				errorCode,
+				isSocket: false,
+			};
+			// Only a refused Unix-domain socket path can be considered stale, and
+			// even then only when the path really is a socket file (a plain file
+			// or directory at the same path must stay "unknown" — never unlink it).
+			if (errorCode === "ECONNREFUSED" && process.platform !== "win32" && typeof socketPath === "string") {
+				try {
+					snapshot.isSocket = lstatSync(socketPath).isSocket() === true;
+				} catch {
+					snapshot.isSocket = false;
+				}
+			}
+			result = buildResult(snapshot, null);
+			finish();
+		};
+
+		try {
+			socket = connect(socketPath);
+		} catch (err) {
+			result = buildResult({ connected: false, protocolValid: false, errorCode: errCode(err), isSocket: false }, null);
+			finish();
+			return;
+		}
+
+		timer = setTimeout(() => finishError("TIMEOUT"), timeoutMs);
+
+		socket.on("error", (err) => {
+			finishError(errCode(err));
+		});
+
+		socket.on("connect", () => {
+			try {
+				socket.write(JSON.stringify({ type: "hello", clientId: "probe", wantOutput: false }) + "\n");
+			} catch (err) {
+				finishError(errCode(err));
+			}
+		});
+
+		socket.on("data", (chunk) => {
+			if (settled) return;
+			buffer += chunk.toString("utf8");
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = buffer.slice(0, newline).trim();
+			const parsed = parseReply(line);
+			result = buildResultFromReply(parsed, expectedViewId, expectedInstanceId);
+			finish();
+		});
+
+		// A close before any data settles the probe as an error-path unknown.
+		socket.on("close", () => {
+			if (!settled) finishError("CLOSED");
+		});
+	});
+}
+
+/**
+ * @param {string} line
+ * @returns {{ ok: boolean, status: any }}
+ */
+function parseReply(line) {
+	if (!line) return { ok: false, status: null };
+	try {
+		const msg = JSON.parse(line);
+		if (!msg || typeof msg !== "object") return { ok: false, status: null };
+		if (msg.type !== "hello" && msg.type !== "status") return { ok: false, status: null };
+		if (!msg.status || typeof msg.status !== "object") return { ok: false, status: null };
+		return { ok: true, status: msg.status };
+	} catch {
+		return { ok: false, status: null };
+	}
+}
+
+/**
+ * Assemble the classify snapshot from a parsed reply.
+ * @param {{ ok: boolean, status: any }} parsed
+ * @param {string|null} expectedViewId
+ * @param {string|null} expectedInstanceId
+ */
+function buildResultFromReply(parsed, expectedViewId, expectedInstanceId) {
+	const status = parsed.ok ? parsed.status : null;
+	const viewMatch = expectedViewId == null ? true : status?.viewId === expectedViewId;
+	const instanceMatch = expectedInstanceId == null ? true : status?.instanceId === expectedInstanceId;
+	// Legacy hosts (pre-instanceId protocol) report alive without a readyAt
+	// field; a legacy probe (no expectedInstanceId) must still classify them
+	// ready so upgrade-window attach keeps working (spec §10.1 / Task 2 ruling).
+	const readyAt = status?.readyAt ?? (expectedInstanceId == null && status?.state === "alive" ? 1 : null);
+	return buildResult(
+		{
+			connected: true,
+			protocolValid: parsed.ok,
+			viewMatch,
+			instanceMatch,
+			state: status?.state ?? null,
+			readyAt,
+		},
+		status,
+	);
+}
+
+/**
+ * @param {{ connected: boolean, protocolValid: boolean, viewMatch?: boolean, instanceMatch?: boolean, state?: string|null, readyAt?: number|null, errorCode?: string|null, isSocket?: boolean }} snapshot
+ * @param {any} status
+ * @returns {ProbeResult}
+ */
+function buildResult(snapshot, status) {
+	const classification = classifyProbeResult(snapshot);
+	return {
+		classification,
+		connected: snapshot.connected === true,
+		protocolValid: snapshot.protocolValid === true,
+		ready: classification === "ready",
+		viewId: status?.viewId ?? null,
+		instanceId: status?.instanceId ?? null,
+		state: snapshot.state ?? null,
+		errorCode: snapshot.errorCode ?? null,
+	};
+}
+
+/** @param {unknown} err */
+function errCode(err) {
+	if (err && typeof err === "object" && typeof /** @type {any} */ (err).code === "string") return /** @type {any} */ (err).code;
+	return "UNKNOWN";
+}