@zhuxixi/pi-agent-board 0.5.2 → 0.6.1

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,68 @@ 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))}…`;
+}
+
+const OSC_SEQUENCE_RE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const CSI_SEQUENCE_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const OTHER_ESCAPE_RE = /\x1b./g;
+
+/**
+ * Last non-empty visible line of a raw terminal log chunk: strips OSC/CSI/ESC
+ * escape sequences, resolves per-line carriage-return overwrites (progress
+ * bars / boot spinners), and returns the final remaining line truncated to
+ * `maxLen`. Used to attribute a failed child's exit reason from screen.log
+ * into host.json (issue #90). Returns null for empty/all-invisible input.
+ * @param {string|null|undefined} text
+ * @param {number} [maxLen]
+ * @returns {string|null}
+ */
+export function lastVisibleLogLine(text, maxLen = 200) {
+	if (!text) return null;
+	const visible = String(text)
+		.replace(OSC_SEQUENCE_RE, "")
+		.replace(CSI_SEQUENCE_RE, "")
+		.replace(OTHER_ESCAPE_RE, "")
+		// A \r directly before \n is a line terminator (CRLF), not an overwrite
+		// marker — normalize it away so the line content survives.
+		.replace(/\r\n/g, "\n");
+	const lines = visible.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		// Trailing \r chars are line-terminator junk (PTY ONLCR + the program's own
+		// CRLF stack up as \r\r\n) — drop them, then resolve interior \r overwrites.
+		const cleaned = lines[i].replace(/\r+$/, "");
+		const cr = cleaned.lastIndexOf("\r");
+		const line = (cr >= 0 ? cleaned.slice(cr + 1) : cleaned).trim();
+		if (line) return truncate(line, maxLen);
+	}
+	return null;
 }
 
 /**

package/src/core/host-coordination.mjs

@@ -0,0 +1,182 @@
+/**
+ * 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";
+}
+
+/**
+ * Whether a legacy (pre-instanceId) host record can be safely finalized as
+ * `exited` so the next attach claims a fresh host. Spec §10.1 keeps legacy
+ * hosts unrecovered because their identity is unverifiable — but a provably
+ * dead runner pid IS a certain identity (a reused pid reads alive, which
+ * conservatively lands here as false), and an unreachable endpoint (missing
+ * socket file / refused socket) rules out a merely slow host. All four
+ * conditions must hold at once (issue #87).
+ * @param {{
+ *   host: HostStatus|null|undefined,
+ *   hostPid: number|null|undefined,
+ *   hostPidAlive: boolean,
+ *   probeClassification: string,
+ * }} input
+ * @returns {boolean}
+ */
+export function canFinalizeLegacyHost({ host, hostPid, hostPidAlive, probeClassification }) {
+	if (!host || host.instanceId != null) return false;
+	if (host.state !== "starting" && host.state !== "alive") return false;
+	if (hostPid == null || hostPidAlive) return false;
+	return probeClassification === "missing" || probeClassification === "stale";
+}
+
+/** 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;
 }