@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/heuristics.mjs

@@ -0,0 +1,313 @@
+/**
+ * Pure text heuristics: extracting assistant text, detecting questions/blockers,
+ * summarizing tool calls, and formatting relative times. No I/O, fully unit-tested.
+ */
+
+/**
+ * Join the text content blocks of an assistant message into a single string.
+ * Accepts the message object as emitted in JSON mode (`message.content` is an array
+ * of `{type,...}` blocks, or, defensively, a plain string).
+ * @param {any} message
+ * @returns {string}
+ */
+export function assistantText(message) {
+	if (!message) return "";
+	const content = message.content;
+	if (typeof content === "string") return 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();
+}
+
+/**
+ * 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
+ * @returns {Array<{name:string, arguments:Record<string,any>}>}
+ */
+export function toolCalls(message) {
+	const content = message?.content;
+	if (!Array.isArray(content)) return [];
+	return content
+		.filter((b) => b && b.type === "toolCall")
+		.map((b) => ({ name: b.name, arguments: b.arguments ?? {} }));
+}
+
+const QUESTION_PHRASES = [
+	"need your input",
+	"need some input",
+	"which option",
+	"should i",
+	"shall i",
+	"please confirm",
+	"could you confirm",
+	"can you confirm",
+	"let me know",
+	"do you want",
+	"would you like",
+	"how would you like",
+	"what would you like",
+	"which one",
+	"please clarify",
+	"can you clarify",
+	"waiting for your",
+];
+
+/**
+ * Decide whether the latest assistant text is asking the user a question / is blocked,
+ * and extract the question sentence if so.
+ * @param {string} text
+ * @returns {{ needsInput: boolean, question: string|null }}
+ */
+export function detectNeedsInput(text) {
+	const trimmed = (text || "").trim();
+	if (!trimmed) return { needsInput: false, question: null };
+
+	const lower = trimmed.toLowerCase();
+	const sentences = splitSentences(trimmed);
+	const last = sentences[sentences.length - 1] ?? trimmed;
+
+	// Strongest signal: the message ends on a question mark.
+	if (/\?\s*$/.test(trimmed)) {
+		const q = [...sentences].reverse().find((s) => s.includes("?")) ?? last;
+		return { needsInput: true, question: q.trim() };
+	}
+
+	for (const phrase of QUESTION_PHRASES) {
+		if (lower.includes(phrase)) {
+			const hit = sentences.find((s) => s.toLowerCase().includes(phrase)) ?? last;
+			return { needsInput: true, question: hit.trim() };
+		}
+	}
+
+	return { needsInput: false, question: null };
+}
+
+/**
+ * Split text into sentences (rough; good enough for previews/blocker extraction).
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitSentences(text) {
+	return (text || "")
+		.replace(/\s+/g, " ")
+		.trim()
+		.split(/(?<=[.!?])\s+/)
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+/**
+ * First sentence (or first line) of an assistant message, for compact previews.
+ * @param {string} text
+ * @returns {string}
+ */
+export function firstSentence(text) {
+	const sentences = splitSentences(text);
+	return sentences[0] ?? "";
+}
+
+const PATH_KEYS = ["file_path", "path", "filePath", "file", "filename"];
+
+/**
+ * Best-effort target path from a tool call's arguments.
+ * @param {Record<string,any>} args
+ * @returns {string|null}
+ */
+export function toolPath(args) {
+	if (!args || typeof args !== "object") return null;
+	for (const k of PATH_KEYS) {
+		if (typeof args[k] === "string" && args[k]) return args[k];
+	}
+	if (typeof args.pattern === "string" && args.pattern) return args.pattern;
+	return null;
+}
+
+/**
+ * Human one-liner for an in-progress tool call, e.g. "Editing src/auth.ts".
+ * @param {string} name
+ * @param {Record<string,any>} args
+ * @returns {string}
+ */
+export function toolSummary(name, args) {
+	const p = toolPath(args);
+	const base = p ? baseName(p) : null;
+	switch (name) {
+		case "edit":
+			return base ? `Editing ${base}` : "Editing files";
+		case "write":
+			return base ? `Writing ${base}` : "Writing files";
+		case "read":
+			return base ? `Reading ${base}` : "Reading files";
+		case "ls":
+			return base ? `Listing ${base}` : "Listing files";
+		case "find":
+			return p ? `Finding ${p}` : "Finding files";
+		case "grep":
+			return p ? `Searching /${p}/` : "Searching";
+		case "bash": {
+			const cmd = typeof args?.command === "string" ? args.command.trim() : "";
+			if (!cmd) return "Running command";
+			const kind = classifyCommand(cmd);
+			if (kind === "test") return "Running tests";
+			if (kind === "build") return "Building";
+			if (kind === "lint") return "Linting";
+			if (kind === "git") return `git ${cmd.replace(/^git\s+/, "").split(/\s+/)[0] ?? ""}`.trim();
+			return `Running ${truncate(cmd, 32)}`;
+		}
+		default:
+			return base ? `${capitalize(name)} ${base}` : capitalize(name);
+	}
+}
+
+/**
+ * Classify a shell command for review evidence.
+ * @param {string} command
+ * @returns {"test"|"build"|"lint"|"git"|"install"|"other"}
+ */
+export function classifyCommand(command) {
+	const cmd = String(command || "").trim();
+	if (!cmd) return "other";
+	if (/\b(test|vitest|jest|pytest|go test|cargo test|npm test|pnpm test|yarn test)\b/.test(cmd)) return "test";
+	if (/\b(build|tsc|webpack|vite build|make|cargo build|go build)\b/.test(cmd)) return "build";
+	if (/\b(lint|eslint|biome|ruff|clippy)\b/.test(cmd)) return "lint";
+	if (/^(git|gh)\b/.test(cmd)) return "git";
+	if (/\b(npm install|npm ci|pnpm install|yarn install|bun install)\b/.test(cmd)) return "install";
+	return "other";
+}
+
+/** @param {string} command @param {number} [n] */
+export function commandPreview(command, n = 120) {
+	return truncate(String(command || "").replace(/\s+/g, " ").trim(), n);
+}
+
+/**
+ * Detect file mutation operations from tool name/args.
+ * @param {string} name
+ * @param {Record<string,any>} args
+ * @returns {{ path:string, action:"edited"|"written"|"deleted"|"unknown" }|null}
+ */
+export function toolFileOperation(name, args) {
+	const p = toolPath(args);
+	if (!p) return null;
+	if (["edit", "multi_edit", "apply_patch"].includes(name)) return { path: p, action: "edited" };
+	if (["write", "create_file"].includes(name)) return { path: p, action: "written" };
+	if (["delete", "rm", "remove_file"].includes(name)) return { path: p, action: "deleted" };
+	return null;
+}
+
+/** @param {string} p */
+export function baseName(p) {
+	const parts = String(p).split(/[\\/]/).filter(Boolean);
+	return parts[parts.length - 1] ?? p;
+}
+
+/** @param {string} s */
+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 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;
+}
+
+/**
+ * Compact relative age, e.g. "10s", "2m", "3h", "4d".
+ * @param {number} fromMs
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+export function relativeTime(fromMs, nowMs = Date.now()) {
+	const diff = Math.max(0, nowMs - fromMs);
+	const s = Math.floor(diff / 1000);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h`;
+	const d = Math.floor(h / 24);
+	return `${d}d`;
+}

package/packages/board/src/core/hold-input.mjs

@@ -0,0 +1,27 @@
+/**
+ * While the board or an attached session is on screen, it owns the keyboard. Pi offers extensions'
+ * key listeners every key first, so without this a listener in the Pi behind the overlay can take a
+ * key: pi-modes' Shift+Tab, for one, changed that Pi's permission mode and never reached the session.
+ *
+ * Fullscreen Pi's mouse handling is a listener too, and has to keep running. It's added when the TUI
+ * is built, so it's first in the set. Listeners added or removed meanwhile, as a session change does,
+ * still apply once released. Does nothing if pi-tui changes shape, which leaves today's behavior.
+ *
+ * @param {any} tui
+ * @returns {() => void} gives the keys back
+ */
+export function holdInputListeners(tui) {
+	const listeners = tui?.inputListeners;
+	if (!(listeners instanceof Set)) return () => {};
+	const kept = typeof tui.handleViewportInput === "function" ? [...listeners].slice(0, 1) : [];
+	const held = {
+		size: kept.length,
+		add: (listener) => listeners.add(listener),
+		delete: (listener) => listeners.delete(listener),
+		[Symbol.iterator]: () => kept[Symbol.iterator](),
+	};
+	tui.inputListeners = held;
+	return () => {
+		if (tui.inputListeners === held) tui.inputListeners = listeners;
+	};
+}

package/packages/board/src/core/host-coordination.mjs

@@ -0,0 +1,300 @@
+/**
+ * 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.
+ *
+ * `not_started` requires BOTH the identity and `spawnedAt` to be absent: a
+ * recorded identity is proof the spawn happened, so such a record is judged by
+ * the observation. Calling it `not_started` (a releasable state) on a
+ * spawned-but-incomplete record could release a still-live host and let a new
+ * host double-write the session file.
+ * @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 && identity == 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";
+}
+
+/** Characters that may abut a path fragment in a command line without being part of it. */
+const COMMAND_LINE_BOUNDARIES = /[\s"']/;
+
+/** Windows path semantics: separators and case are not significant. */
+function normalizeCommandLine(text) {
+	return text.replace(/\\/g, "/").toLowerCase();
+}
+
+function isCommandLineBoundary(text, index, length) {
+	const before = index === 0 ? null : text[index - 1];
+	const after = index + length >= text.length ? null : text[index + length];
+	return (before == null || COMMAND_LINE_BOUNDARIES.test(before)) && (after == null || COMMAND_LINE_BOUNDARIES.test(after));
+}
+
+/**
+ * Whether a process command line mentions `fragment` as a whole path, not as a
+ * prefix of a longer one (`view_abc` must not match `view_abcd`, nor
+ * `session.jsonl` match `session-2.jsonl`). Comparison is slash- and
+ * case-insensitive because Windows reports `C:\x\y` inside quotes while the
+ * recorded fragment is a plain path (issue #217). Empty/missing input is never
+ * a match: a blank fragment would otherwise corroborate any process.
+ * @param {string|null|undefined} commandLine
+ * @param {string|null|undefined} fragment
+ * @returns {boolean}
+ */
+export function commandLineMentions(commandLine, fragment) {
+	if (!commandLine || !fragment) return false;
+	const haystack = normalizeCommandLine(commandLine);
+	const needle = normalizeCommandLine(fragment);
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		if (isCommandLineBoundary(haystack, index, needle.length)) return true;
+		index = haystack.indexOf(needle, index + 1);
+	}
+	return false;
+}
+
+/**
+ * Refine a host-role observation that the token path could only call `unknown`
+ * (platforms without a start token) using deterministic probe evidence
+ * (issue #217). The command line is authoritative because every host role we
+ * spawn carries its own unique path argument; process creation time only
+ * corroborates when the command line is unreadable, and the tolerance absorbs
+ * spawn→record skew. A missing probe stays `unknown` — the #70 contract: an
+ * unverifiable process is never guessed as foreign.
+ * @param {{
+ *   spawnedAt: number|null,
+ *   probe: {creationTimeMs: number|null, commandLine: string|null}|null,
+ *   expectedCommandFragment: string|null,
+ *   toleranceMs: number,
+ * }} input
+ * @returns {"owned"|"foreign"|"unknown"}
+ */
+export function classifyUnverifiableProcess({ spawnedAt, probe, expectedCommandFragment, toleranceMs }) {
+	if (!probe) return "unknown";
+	if (probe.commandLine && expectedCommandFragment) {
+		return commandLineMentions(probe.commandLine, expectedCommandFragment) ? "owned" : "foreign";
+	}
+	if (spawnedAt == null || probe.creationTimeMs == null) return "unknown";
+	return Math.abs(probe.creationTimeMs - spawnedAt) <= toleranceMs ? "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. The runner and
+ * child roles must be provably gone; any `unknown` observation or an active
+ * launch lease blocks replacement. The claim role does NOT participate: claim
+ * protection (a launcher mid-transaction between claim and spawn) only matters
+ * while the host is `starting`, and this gate only ever sees terminal hosts —
+ * a terminal host cannot still be being launched (issue #99: a live claimPid —
+ * the dashboard process that wrote the claim — must not block re-attach).
+ * @param {{
+ *   host: HostStatus|null|undefined,
+ *   runnerObservation: string,
+ *   childObservation: string,
+ *   launchLeaseActive: boolean,
+ * }} input
+ * @returns {boolean}
+ */
+export function canReplaceHost({ host, runnerObservation, childObservation, 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)
+	);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Whether this instance may unlink the endpoint path now.
+ * Restores the #70 cleanup contract (docs/superpowers/specs/
+ * 2026-09-05-pty-host-stacking-sock-race-design.md:418): the path must still be
+ * the inode this instance bound AND this instance must still own the lease.
+ * `compromised` lets the supervised tick veto its own cleanup after detecting
+ * that the endpoint is gone or replaced (issue #255).
+ * @param {{
+ *   stillOwner: boolean,
+ *   compromised: boolean,
+ *   bound: {dev:number,ino:number}|null|undefined,
+ *   current: {dev:number,ino:number}|null|undefined,
+ * }} input
+ * @returns {boolean}
+ */
+export function shouldUnlinkEndpoint({ stillOwner, compromised, bound, current }) {
+	if (!stillOwner || compromised) return false;
+	return ownsEndpoint(bound, current);
+}
+
+/**
+ * Map one supervised stat attempt to the endpoint observation discriminator.
+ * A transient stat failure (EACCES/EBUSY/...) must never be read as "replaced":
+ * only ENOENT means the endpoint is actually gone (issue #255, mirrors the
+ * rootVanishedOrReplaced rule of issue #241).
+ * @param {{dev:number,ino:number}|null} stat The successful stat snapshot, or null.
+ * @param {string|null} errorCode The stat error code, or null on success.
+ * @returns {{kind:"ok",dev:number,ino:number}|{kind:"missing"}|{kind:"unknown"}}
+ */
+export function socketIdentityObservation(stat, errorCode) {
+	if (stat) return { kind: "ok", dev: stat.dev, ino: stat.ino };
+	return errorCode === "ENOENT" ? { kind: "missing" } : { kind: "unknown" };
+}
+
+/**
+ * Classify the supervised endpoint against the identity bound at boot.
+ * `unknown` never steps a holder down: without a bound identity (win32, or a
+ * failed bind-time stat) the supervisor degrades to a no-op.
+ * @param {{dev:number,ino:number}|null|undefined} bound
+ * @param {{kind:"ok",dev:number,ino:number}|{kind:"missing"}|{kind:"unknown"}|null|undefined} observed
+ * @returns {"ok"|"missing"|"replaced"|"unknown"}
+ */
+export function classifyEndpointHealth(bound, observed) {
+	if (!bound || !observed || observed.kind === "unknown") return "unknown";
+	if (observed.kind === "missing") return "missing";
+	return ownsEndpoint(bound, observed) ? "ok" : "replaced";
+}
+
+/**
+ * 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;
+}