@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/auto-state.mjs

@@ -0,0 +1,377 @@
+/**
+ * Automatic terminal-state classification for finished agent turns.
+ *
+ * The dashboard has three user-facing post-run buckets:
+ *   - needs_input  → agent is waiting on the user
+ *   - idle         → in progress / worth revisiting
+ *   - completed    → done
+ *
+ * This module is pure (no model/network I/O). Runners may feed model JSON into
+ * parseAutoStateModelOutput(); otherwise heuristicAutoState() gives a safe fallback.
+ */
+import { createHash } from "node:crypto";
+import { deriveSummary } from "./derive.mjs";
+import { detectNeedsInput, firstSentence, splitSentences, truncate } from "./heuristics.mjs";
+
+/** @typedef {import("./types.mjs").SemanticState} SemanticState */
+/** @typedef {"needs_input"|"in_progress"|"done"} AutoStateKind */
+/** @typedef {"model"|"heuristic"} AutoStateSource */
+/** @typedef {"high"|"medium"|"low"} AutoStateConfidence */
+
+const AUTO_STATE_KINDS = new Set(["needs_input", "in_progress", "done"]);
+const CONFIDENCES = new Set(["high", "medium", "low"]);
+const DEFAULT_AUTO_STATE_MODEL = "gpt-4o";
+
+/** @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env] */
+export function autoStateEnabled(env = process.env) {
+	const raw = env.AGENT_BOARD_AUTO_STATE ?? env.AGENT_VIEW_AUTO_STATE;
+	return !isOff(raw);
+}
+
+/** @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env] */
+export function autoStateModel(env = process.env) {
+	const configured = env.AGENT_BOARD_AUTO_STATE_MODEL ?? env.AGENT_VIEW_AUTO_STATE_MODEL;
+	if (isOff(configured)) return null;
+	return configured || DEFAULT_AUTO_STATE_MODEL;
+}
+
+/** @param {string|undefined} value */
+function isOff(value) {
+	return typeof value === "string" && /^(0|false|off|no)$/i.test(value.trim());
+}
+
+/**
+ * Whether automatic `done` classification is disabled.
+ * Default (env unset): disabled — completed is only ever set by the user.
+ * Set AGENT_BOARD_AUTO_STATE_NO_DONE to 0/false/off/no to restore auto-done.
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env]
+ */
+export function autoStateDoneDisabled(env = process.env) {
+	const raw = env.AGENT_BOARD_AUTO_STATE_NO_DONE;
+	if (typeof raw !== "string" || !raw.trim()) return true;
+	return !isOff(raw);
+}
+
+/** @param {AutoStateKind} kind @returns {SemanticState} */
+export function semanticStateForAutoKind(kind) {
+	switch (kind) {
+		case "needs_input":
+			return "needs_input";
+		case "done":
+			return "completed";
+		default:
+			return "idle";
+	}
+}
+
+/**
+ * Prompt used by runners for the cheap classifier pass.
+ * @param {string} latestAssistantText
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env]
+ */
+export function buildAutoStatePrompt(latestAssistantText, env = process.env) {
+	const text = truncate(String(latestAssistantText || "").trim(), 6000);
+	const doneLine = autoStateDoneDisabled(env)
+		? ""
+		: "- done: the requested work is complete, final answer given, no user input required.\n";
+	const doneNote = autoStateDoneDisabled(env)
+		? "The user marks completed manually in the dashboard, so completion signals (done/completed/finished) must be classified as in_progress.\n"
+		: "";
+	const states = autoStateDoneDisabled(env) ? "needs_input|in_progress" : "needs_input|in_progress|done";
+	return `Classify the LAST assistant response for a coding-agent dashboard.\n\nChoose exactly one state:\n- needs_input: the assistant asks the user for a decision, clarification, approval, credentials, or is blocked waiting for the user.\n- in_progress: work is partial, next steps remain, verification is pending/failed, or the assistant says it will continue later.\n${doneLine}${doneNote}\nReturn ONLY minified JSON with this shape:\n{"state":"${states}","confidence":"high|medium|low","reason":"short reason <=18 words","question":"user-facing question or null"}\n\nLast assistant response:\n${text}`;
+}
+
+/**
+ * Parse and normalize model JSON. Returns null if the response is unusable.
+ * @param {string} raw
+ * @param {{ latestAssistantText?: string, now?: number, lastAgentActivityAt?: number|null, env?: NodeJS.ProcessEnv|Record<string,string|undefined> }} [opts]
+ */
+export function parseAutoStateModelOutput(raw, opts = {}) {
+	const obj = extractJsonObject(raw);
+	if (!obj) return null;
+	let kind = normalizeKind(obj.state ?? obj.kind ?? obj.status);
+	if (!kind) return null;
+	let downgraded = false;
+	if (kind === "done" && autoStateDoneDisabled(opts.env ?? process.env)) {
+		kind = "in_progress";
+		downgraded = true;
+	}
+	const confidence = normalizeConfidence(obj.confidence);
+	const latest = opts.latestAssistantText ?? "";
+	const nb = detectNeedsInput(latest);
+	const question = kind === "needs_input" ? cleanQuestion(obj.question) || nb.question || latestQuestion(latest) : null;
+	return makeClassification(kind, {
+		source: "model",
+		confidence,
+		reason: downgraded
+			? "Model reported done but auto-done is disabled"
+			: cleanReason(obj.reason) || defaultReason(kind),
+		question,
+		now: opts.now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		latestAssistantText: latest,
+	});
+}
+
+/**
+ * Conservative fallback classifier. It should be useful, but never clever enough to
+ * overrule strong question/error signals.
+ * @param {string} latestAssistantText
+ * @param {{ now?: number, lastAgentActivityAt?: number|null, env?: NodeJS.ProcessEnv|Record<string,string|undefined> }} [opts]
+ */
+export function heuristicAutoState(latestAssistantText, opts = {}) {
+	const text = String(latestAssistantText || "").trim();
+	const nb = detectNeedsInput(text);
+	if (nb.needsInput) {
+		return makeClassification("needs_input", {
+			source: "heuristic",
+			confidence: "high",
+			reason: "Assistant asked for user input",
+			question: nb.question,
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+
+	const lower = text.toLowerCase();
+	const pending = hasPendingSignal(lower);
+	const done = hasDoneSignal(lower);
+	const env = opts.env ?? process.env;
+	if (done && !pending && !autoStateDoneDisabled(env)) {
+		return makeClassification("done", {
+			source: "heuristic",
+			confidence: hasStrongDoneSignal(lower) ? "high" : "medium",
+			reason: "Assistant reported the work is complete",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+	if (done && !pending) {
+		// Auto-done disabled: completion signals stay out of the completed bucket;
+		// the user marks completed manually from the dashboard.
+		return makeClassification("in_progress", {
+			source: "heuristic",
+			confidence: hasStrongDoneSignal(lower) ? "medium" : "low",
+			reason: "Assistant reported completion but auto-done is disabled",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+	if (pending) {
+		return makeClassification("in_progress", {
+			source: "heuristic",
+			confidence: "medium",
+			reason: "Assistant mentioned remaining work or pending verification",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+	return makeClassification("in_progress", {
+		source: "heuristic",
+		confidence: "low",
+		reason: "No clear completion or input signal",
+		now: opts.now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		latestAssistantText: text,
+	});
+}
+
+/**
+ * Pick a model classification when valid, otherwise fall back to heuristics.
+ * @param {string} modelOutput
+ * @param {string} latestAssistantText
+ * @param {{ now?: number, lastAgentActivityAt?: number|null }} [opts]
+ */
+export function autoStateFromModelOrHeuristic(modelOutput, latestAssistantText, opts = {}) {
+	return parseAutoStateModelOutput(modelOutput, { latestAssistantText, ...opts }) ?? heuristicAutoState(latestAssistantText, opts);
+}
+
+/**
+ * Whether a row/status carries a manual verdict (issue #145): the user placed a
+ * terminal judgment ("completed" or "holding") that no automated writer may
+ * overwrite. mark_completed and mark_holding both clear autoState on
+ * state.json and status.json, so `autoState == null` combined with a verdict
+ * state is the persisted signal. Wide on purpose (spec D15): no call site
+ * needs a completed-only predicate.
+ * @param {{ semanticState?: string, autoState?: unknown|null }|null|undefined} state
+ */
+export function isManualVerdict(state) {
+	return Boolean(state && (state.semanticState === "completed" || state.semanticState === "holding") && state.autoState == null);
+}
+
+/**
+ * Mutate a RunStatus with a classification. Returns true if state/metadata changed.
+ * @param {import("./types.mjs").RunStatus} status
+ * @param {import("./types.mjs").AutoStateClassification} classification
+ * @param {number} [now]
+ */
+export function applyAutoStateToStatus(status, classification, now = Date.now()) {
+	if (!classification || status.processState === "alive") return false;
+	if (status.semanticState === "failed" || status.semanticState === "stopped") return false;
+	// Manual verdicts are user judgments and must never be overwritten.
+	if (isManualVerdict(status)) return false;
+	const nextState = semanticStateForAutoKind(classification.kind);
+	const before = `${status.semanticState}|${status.question ?? ""}|${status.summary ?? ""}|${status.autoState?.source ?? ""}|${status.autoState?.textHash ?? ""}`;
+	status.semanticState = nextState;
+	status.autoState = { ...classification, semanticState: nextState, classifiedAt: now };
+	if (nextState === "needs_input") {
+		status.question = classification.question || detectNeedsInput(status.latestAssistantPreview).question || latestQuestion(status.latestAssistantPreview);
+	} else {
+		status.question = null;
+	}
+	status.summary = deriveSummary(status);
+	const after = `${status.semanticState}|${status.question ?? ""}|${status.summary ?? ""}|${status.autoState?.source ?? ""}|${status.autoState?.textHash ?? ""}`;
+	return before !== after;
+}
+
+/**
+ * Mutate a ViewState with a classification. Returns true if state/metadata changed.
+ * @param {import("./types.mjs").ViewState} state
+ * @param {import("./types.mjs").AutoStateClassification} classification
+ * @param {number} [now]
+ */
+export function applyAutoStateToViewState(state, classification, now = Date.now()) {
+	if (!classification || state.processState === "alive") return false;
+	if (state.semanticState === "failed" || state.semanticState === "stopped") return false;
+	// Manual verdicts are user judgments and must never be overwritten.
+	if (isManualVerdict(state)) return false;
+	const nextState = semanticStateForAutoKind(classification.kind);
+	const before = `${state.semanticState}|${state.question ?? ""}|${state.summary ?? ""}|${state.autoState?.source ?? ""}|${state.autoState?.textHash ?? ""}`;
+	state.semanticState = nextState;
+	state.needsInput = nextState === "needs_input";
+	state.hasError = nextState === "failed";
+	state.autoState = { ...classification, semanticState: nextState, classifiedAt: now };
+	if (nextState === "needs_input") {
+		state.question = classification.question || detectNeedsInput(state.latestAssistantPreview).question || latestQuestion(state.latestAssistantPreview);
+	} else {
+		state.question = null;
+	}
+	state.error = nextState === "failed" ? state.error : null;
+	state.updatedAt = now;
+	state.summary = deriveSummary({
+		processState: state.processState,
+		semanticState: state.semanticState,
+		currentTool: state.latestTool,
+		question: state.question,
+		error: state.error,
+		latestAssistantPreview: state.latestAssistantPreview,
+	});
+	const after = `${state.semanticState}|${state.question ?? ""}|${state.summary ?? ""}|${state.autoState?.source ?? ""}|${state.autoState?.textHash ?? ""}`;
+	return before !== after;
+}
+
+/**
+ * @param {AutoStateKind} kind
+ * @param {{ source: AutoStateSource, confidence?: AutoStateConfidence, reason?: string, question?: string|null, now?: number, lastAgentActivityAt?: number|null, latestAssistantText?: string }} opts
+ * @returns {import("./types.mjs").AutoStateClassification}
+ */
+function makeClassification(kind, opts) {
+	const now = opts.now ?? Date.now();
+	const semanticState = semanticStateForAutoKind(kind);
+	return {
+		version: 1,
+		kind,
+		semanticState,
+		confidence: opts.confidence ?? "low",
+		source: opts.source,
+		reason: truncate(String(opts.reason || defaultReason(kind)).replace(/\s+/g, " ").trim(), 120),
+		question: opts.question ? truncate(String(opts.question).replace(/\s+/g, " ").trim(), 240) : null,
+		classifiedAt: now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		textHash: textHash(opts.latestAssistantText ?? ""),
+	};
+}
+
+/** @param {string} raw */
+function extractJsonObject(raw) {
+	const text = String(raw || "").trim();
+	if (!text) return null;
+	const candidates = [text];
+	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+	if (fenced) candidates.unshift(fenced[1].trim());
+	const first = text.indexOf("{");
+	const last = text.lastIndexOf("}");
+	if (first >= 0 && last > first) candidates.unshift(text.slice(first, last + 1));
+	for (const candidate of candidates) {
+		try {
+			const parsed = JSON.parse(candidate);
+			if (parsed && typeof parsed === "object") return parsed;
+		} catch {
+			/* try next */
+		}
+	}
+	return null;
+}
+
+/** @param {any} value @returns {AutoStateKind|null} */
+function normalizeKind(value) {
+	const s = String(value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	if (AUTO_STATE_KINDS.has(s)) return /** @type {AutoStateKind} */ (s);
+	if (["needsinput", "input", "input_required", "requires_input", "awaiting_input", "blocked", "question"].includes(s)) return "needs_input";
+	if (["progress", "ongoing", "continue", "continuing", "partial", "not_done", "todo"].includes(s)) return "in_progress";
+	if (["complete", "completed", "finished", "finish", "success", "resolved"].includes(s)) return "done";
+	return null;
+}
+
+/** @param {any} value @returns {AutoStateConfidence} */
+function normalizeConfidence(value) {
+	const s = String(value ?? "medium").toLowerCase().trim();
+	return CONFIDENCES.has(s) ? /** @type {AutoStateConfidence} */ (s) : "medium";
+}
+
+/** @param {any} value */
+function cleanReason(value) {
+	return String(value ?? "").replace(/\s+/g, " ").trim();
+}
+
+/** @param {any} value */
+function cleanQuestion(value) {
+	const s = String(value ?? "").replace(/\s+/g, " ").trim();
+	if (!s || /^null$/i.test(s) || /^none$/i.test(s)) return null;
+	return s;
+}
+
+/** @param {AutoStateKind} kind */
+function defaultReason(kind) {
+	switch (kind) {
+		case "needs_input":
+			return "Assistant is waiting for user input";
+		case "done":
+			return "Assistant reported completion";
+		default:
+			return "Assistant appears to have more work remaining";
+	}
+}
+
+/** @param {string} text */
+function latestQuestion(text) {
+	const sentences = splitSentences(text);
+	return [...sentences].reverse().find((s) => /\?\s*$/.test(s)) ?? null;
+}
+
+/** @param {string} lower */
+function hasStrongDoneSignal(lower) {
+	return /(^|\b)(done|completed|complete|finished|resolved|all set|implemented|shipped)(\b|[.!])/i.test(lower) || /tests? (pass|passed|passing)/i.test(lower);
+}
+
+/** @param {string} lower */
+function hasDoneSignal(lower) {
+	return hasStrongDoneSignal(lower)
+		|| /\b(final answer|summary:|i'?ve (fixed|updated|added|implemented)|successfully|ready to go)\b/i.test(lower)
+		|| firstSentence(lower).length > 0 && /^done[.!]/i.test(firstSentence(lower));
+}
+
+/** @param {string} lower */
+function hasPendingSignal(lower) {
+	return /\b(todo|next steps?|remaining|still need|need to|not yet|pending|in progress|continue|will continue|i'?ll continue|i will|follow up|not run|couldn'?t run|unable to run|blocked|waiting for)\b/i.test(lower)
+		|| /\btests? (fail|failed|failing|pending|not run|weren'?t run|couldn'?t be run)\b/i.test(lower);
+}
+
+/** @param {string} text */
+function textHash(text) {
+	return createHash("sha1").update(String(text || "")).digest("hex").slice(0, 12);
+}

package/packages/board/src/core/background-runs.mjs

@@ -0,0 +1,273 @@
+/**
+ * Background-workflow run detection for warm-host eviction (issue #230).
+ *
+ * A warm host whose session owns a `running` pi-workflow run must not be swept:
+ * eviction revokes the host, the child pi gets SIGTERM, and the in-flight agent
+ * step turns into a `skipped/interrupted` event — the run ends `paused` while the
+ * user is never told. The sweeper cannot see this from row state because
+ * `workflow({ background: true })` returns `started` before the step finishes, so
+ * the row falls back to `idle` and looks evictable.
+ *
+ * This module is the decision core plus its thin IO shell: parse a run head
+ * record, match it to a row's session file, classify the protection outcome, and
+ * enumerate/probe the on-disk run store (`scanBackgroundRuns`/`probeBackgroundRun`).
+ * Design: docs/superpowers/specs/2026-10-24-issue-230-warm-host-background-runs-design.md
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Timestamp tolerance for FS mtime granularity and cross-process clock skew
+ *  when comparing a run's `updatedAt` against the host start time (spec D1). */
+export const CLOCK_EPSILON_MS = 2000;
+
+/**
+ * @typedef {Object} RunHead
+ * @property {string} runId
+ * @property {string} status
+ * @property {string|null} parentSessionFile legacy records carry none
+ * @property {number|null} startedAtMs
+ * @property {number|null} updatedAtMs
+ * @property {boolean} hasCheckpoint
+ */
+
+/** @typedef {"protecting"|"paused"|"irrelevant"} RunVerdict */
+
+/**
+ * Root directory of pi-dynamic-workflows: `$AGENT_BOARD_WORKFLOW_HOME` (explicit
+ * override) > `$PI_CODING_AGENT_DIR/workflows` > `<home>/.pi/workflows`.
+ * Both `env` and `home` are injectable so callers and tests never depend on the
+ * ambient environment or the real homedir.
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [o]
+ * @returns {string}
+ */
+export function resolveWorkflowHome({ env = process.env, home = os.homedir() } = {}) {
+	const expand = (p) => (p.startsWith("~") ? home + p.slice(1) : p);
+	const explicit = env.AGENT_BOARD_WORKFLOW_HOME;
+	if (typeof explicit === "string" && explicit.length > 0) return expand(explicit);
+	const agentDir = env.PI_CODING_AGENT_DIR;
+	const base = typeof agentDir === "string" && agentDir.length > 0 ? expand(agentDir) : joinPath(home, ".pi");
+	return joinPath(base, "workflows");
+}
+
+/**
+ * Parse a run head record into the fields the protection decision needs, or
+ * `null` when it is not a workflow run. A v2 record nests the run fields under
+ * `index` but keeps `summary` (and therefore the checkpoint) as a sibling at the
+ * record root; legacy flat records carry `checkpoint` at the root themselves and
+ * can never match a row because they have no `parentSessionFile` (spec non-goal:
+ * no legacy session matching).
+ * Never throws: the input is external, unversioned JSON.
+ * @param {unknown} raw parsed JSON
+ * @returns {RunHead|null}
+ */
+export function parseRunHead(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+	const record = /** @type {Record<string, any>} */ (raw);
+	const source = record.format === "pi-workflow-run-v2" ? record.index : record;
+	if (typeof source !== "object" || source === null || Array.isArray(source)) return null;
+	if (typeof source.runId !== "string") return null;
+	return {
+		runId: source.runId,
+		status: typeof source.status === "string" ? source.status : "",
+		parentSessionFile: typeof source.parentSessionFile === "string" ? source.parentSessionFile : null,
+		startedAtMs: toMs(source.startedAt),
+		updatedAtMs: toMs(source.updatedAt),
+		hasCheckpoint: Boolean(record.summary?.checkpoint ?? source.checkpoint),
+	};
+}
+
+/**
+ * Whether two spellings point at the same session file. win32 compares
+ * case-insensitively (the row meta and the workflow record disagree on drive
+ * letter and segment casing; they also mix `\` and `/`); POSIX stays
+ * case-sensitive. `platform` is injectable because CI only runs Linux, so the
+ * win32 branch would otherwise be untested (spec A5).
+ * @param {string} a
+ * @param {string} b
+ * @param {{ platform?: string }} [o]
+ * @returns {boolean}
+ */
+export function isSameSessionFile(a, b, { platform = process.platform } = {}) {
+	if (typeof a !== "string" || typeof b !== "string" || a.length === 0 || b.length === 0) return false;
+	const impl = platform === "win32" ? path.win32 : path.posix;
+	const na = impl.resolve(a);
+	const nb = impl.resolve(b);
+	return platform === "win32" ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+
+/**
+ * Protection verdict for one run against one row (spec D1/D2).
+ *
+ * Order matters: a run belonging to another session is always irrelevant (a
+ * running or paused run of a sibling row must never keep this host alive);
+ * `paused` is reported separately because a paused run needs no host at all and
+ * only drives the "run was interrupted" notice; a running run protects only when
+ * it was updated after the host started, so a stale `running` record left behind
+ * by a previous host incarnation cannot exempt the row forever.
+ * @param {RunHead|null|undefined} run
+ * @param {{ sessionFile: string|null|undefined, hostStartedAt: number|null|undefined }} o
+ * @returns {RunVerdict}
+ */
+export function classifyRunForRow(run, { sessionFile, hostStartedAt }) {
+	if (!run || !run.parentSessionFile) return "irrelevant";
+	if (!isSameSessionFile(run.parentSessionFile, sessionFile)) return "irrelevant";
+	if (run.status === "paused") return "paused";
+	if (run.status !== "running") return "irrelevant";
+	if (hostStartedAt == null || run.updatedAtMs == null) return "protecting";
+	if (run.updatedAtMs >= hostStartedAt - CLOCK_EPSILON_MS) return "protecting";
+	return "irrelevant";
+}
+
+/**
+ * Strongest verdict across a scanned head list: protecting > paused >
+ * irrelevant. Returns the run that produced it so callers can name its runId in
+ * a diagnostic or a row notice; `run` is null for "irrelevant".
+ * @param {Array<RunHead|null|undefined>} runs
+ * @param {{ sessionFile: string|null|undefined, hostStartedAt: number|null|undefined }} o
+ * @returns {{ state: RunVerdict, run: RunHead|null }}
+ */
+export function classifyRunsForRow(runs, o) {
+	let state = /** @type {RunVerdict} */ ("irrelevant");
+	let match = null;
+	for (const run of Array.isArray(runs) ? runs : []) {
+		const verdict = classifyRunForRow(run, o);
+		if (verdict === "protecting") return { state: "protecting", run };
+		if (verdict === "paused" && state === "irrelevant") {
+			state = "paused";
+			match = run;
+		}
+	}
+	return { state, run: match };
+}
+
+/**
+ * @typedef {RunHead & { path: string, mtimeMs: number }} RunHeadWithPath
+ */
+
+/**
+ * Enumerate every run head under `<workflowHome>/projects/<project>/runs/`.
+ * Only `*.json` regular files are candidates (upstream keeps `.bak`,
+ * `.events.jsonl`, `.log` and `.result-*` siblings next to the head), and
+ * `minMtimeMs` drops heads too old to belong to a live host — a prefilter only,
+ * the protection verdict still comes from `classifyRunsForRow`.
+ *
+ * Failure policy (spec D6): an absent store is normal and yields `ok:true`; any
+ * incomplete scan yields `ok:false` so the caller logs a `warm_prune_probe_failed`
+ * diagnostic instead of silently guessing. An incomplete scan is any unreadable
+ * directory or head file, including corrupt JSON — the eviction outcome is the
+ * same either way (a run that cannot be read protects nothing), but only
+ * `ok:false` marks the coverage as incomplete (it does not disable protection).
+ * Heads that were read successfully are still returned and still participate in
+ * the protection classification; a run that could not be read simply has no
+ * evidence and protects nothing. A head file that parses but is not a run head
+ * (`parseRunHead` → null) is not an error: it is simply not a candidate.
+ * The store root is stat-ed before the child paths are enumerated because on
+ * win32 a child path under a regular file reports `ENOENT` exactly like a
+ * missing directory does: a missing `workflowHome` is "no store yet", a
+ * `workflowHome` that is not a directory is a read failure.
+ * @param {{ workflowHome: string, minMtimeMs?: number }} o
+ * @returns {{ ok: boolean, heads: Array<RunHeadWithPath>, error: string|null }}
+ */
+export function scanBackgroundRuns({ workflowHome, minMtimeMs = 0 }) {
+	const heads = [];
+	let error = null;
+	const noteError = (message) => {
+		error ??= message;
+	};
+
+	let projects;
+	try {
+		if (!statSync(workflowHome).isDirectory()) {
+			return { ok: false, heads: [], error: `workflow home is not a directory: ${workflowHome}` };
+		}
+		projects = readdirSync(joinPath(workflowHome, "projects"), { withFileTypes: true });
+	} catch (e) {
+		if (e?.code === "ENOENT") return { ok: true, heads: [], error: null };
+		return { ok: false, heads: [], error: errorMessage(e) };
+	}
+
+	for (const project of projects) {
+		if (!project.isDirectory()) continue;
+		const runsDir = joinPath(workflowHome, "projects", project.name, "runs");
+		let entries;
+		try {
+			entries = readdirSync(runsDir, { withFileTypes: true });
+		} catch (e) {
+			if (e?.code !== "ENOENT") noteError(`${runsDir}: ${errorMessage(e)}`);
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+			const filePath = joinPath(runsDir, entry.name);
+			try {
+				const mtimeMs = statSync(filePath).mtimeMs;
+				if (mtimeMs < minMtimeMs) continue;
+				const head = parseRunHead(JSON.parse(readFileSync(filePath, "utf8")));
+				if (head) heads.push({ ...head, path: filePath, mtimeMs });
+			} catch (e) {
+				noteError(`${filePath}: ${errorMessage(e)}`);
+			}
+		}
+	}
+
+	return { ok: error === null, heads, error };
+}
+
+/**
+ * Fresh protection probe for one row: the scan prefiltered to runs that could
+ * have been updated by this host incarnation, classified against the row's
+ * session file. Each field answers one question and is filled independently
+ * (design §5.1: a running/paused split): `running` is the run that must keep the
+ * host alive (spec D1), `paused` is the run whose interruption the reconcile
+ * pass announces (spec D2). They coexist because one session may hold an older
+ * paused run while a new one is running, and each consumer reads one field.
+ * `ok:false` only means the store could not be read (spec D6).
+ * @param {{ sessionFile: string|null, hostStartedAt: number|null, workflowHome: string }} o
+ * @returns {{ ok: boolean, running: RunHeadWithPath|null, paused: RunHeadWithPath|null, error: string|null }}
+ */
+export function probeBackgroundRun({ sessionFile, hostStartedAt, workflowHome }) {
+	const minMtimeMs = hostStartedAt == null ? 0 : hostStartedAt - CLOCK_EPSILON_MS;
+	const scan = scanBackgroundRuns({ workflowHome, minMtimeMs });
+	if (!scan.ok) return { ok: false, running: null, paused: null, error: scan.error };
+	const verdict = classifyRunsForRow(scan.heads, { sessionFile, hostStartedAt });
+	const running = verdict.state === "protecting" ? verdict.run : null;
+	// Newest paused run wins, because it is the one most likely to be the run the
+	// just-ended host left behind; `path` only breaks ties deterministically.
+	const paused = scan.heads
+		.filter((head) => classifyRunForRow(head, { sessionFile, hostStartedAt }) === "paused")
+		.sort((a, b) => (b.updatedAtMs ?? 0) - (a.updatedAtMs ?? 0) || a.path.localeCompare(b.path))[0] ?? null;
+	return { ok: true, running, paused, error: scan.error };
+}
+
+/**
+ * Join segments with the separator style of the base path. The ambient
+ * `path.join` uses the host separator, which would turn POSIX-style injected
+ * inputs (tests, Linux CI) into backslash paths when the suite runs on Windows,
+ * so the style is read from the base instead of the platform.
+ * @param {string} base
+ * @param {...string} parts
+ * @returns {string}
+ */
+function joinPath(base, ...parts) {
+	const impl = /^[A-Za-z]:/.test(base) || base.includes("\\") ? path.win32 : path.posix;
+	return impl.join(base, ...parts);
+}
+
+/**
+ * @param {unknown} e
+ * @returns {string}
+ */
+function errorMessage(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+function toMs(value) {
+	if (typeof value !== "string") return null;
+	const ms = Date.parse(value);
+	return Number.isFinite(ms) ? ms : null;
+}