@zhuxixi/pi-agent-board 0.5.2 → 0.6.1

package/runner/pty-runner.mjs

@@ -10,16 +10,19 @@
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
-import { existsSync, unlinkSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, statSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { finalizeHostCrash } from "../src/core/host-crash.mjs";
+import { ownsEndpoint, shouldYieldRunner } from "../src/core/host-coordination.mjs";
+import { lastVisibleLogLine } from "../src/core/heuristics.mjs";
+import { acquireOwnedViewLock } from "../src/core/locks.mjs";
 import * as P from "../src/core/paths.mjs";
 import { appendBoundedScreenLog, reconcileScreenLog } from "../src/core/screen-log.mjs";
 import { encodePromptForCliArg } from "../src/core/prompt-transport.mjs";
-import { readState, writeHost, writeState } from "../src/core/store.mjs";
+import { readHost, readState, updateOwnedHost, writeHost, writeState } from "../src/core/store.mjs";
 import { ensureNodePtySpawnHelperExecutable } from "../src/core/pty-support.mjs";
 
 const requireForPty = createRequire(import.meta.url);
@@ -33,6 +36,52 @@ try {
 }
 
 const HEARTBEAT_MS = 1000;
+/** Service-input ack dedup bound (issue #70 Task 8): requestId → true, FIFO evict. */
+const HOST_ACK_DEDUP_MAX = 1000;
+/** Max time an owned runner waits to take the per-view host-start lease (issue #70). */
+const HOST_RUNNER_LOCK_WAIT_MS = 5_000;
+/** How much of the screen.log tail to scan when attributing an abnormal child
+ *  exit (issue #90). Tail-only: the log can be 100MB+. */
+const EXIT_LOG_TAIL_BYTES = 8_192;
+
+/** Tail-read the last `maxBytes` of a file without loading it whole.
+ * @param {string} path
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function readScreenLogTail(path, maxBytes) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+		const size = fstatSync(fd).size;
+		const start = Math.max(0, size - maxBytes);
+		const length = size - start;
+		const buffer = Buffer.allocUnsafe(length);
+		readSync(fd, buffer, 0, length, start);
+		return buffer.toString("utf8");
+	} finally {
+		try { if (fd != null) closeSync(fd); } catch { /* best effort */ }
+	}
+}
+
+/**
+ * Best-effort error attribution for an abnormal child exit (issue #90): the
+ * child's failure reason (e.g. "Model X not found") exists only in the raw
+ * screen log, so surface its last visible line in host.json.error. Never
+ * throws — this runs on the exit path.
+ * @param {number} exitCode
+ * @param {string} screenLogPath
+ * @returns {{} | { error: string }}
+ */
+function attributedExitError(exitCode, screenLogPath) {
+	if (exitCode === 0) return {};
+	try {
+		const line = lastVisibleLogLine(readScreenLogTail(screenLogPath, EXIT_LOG_TAIL_BYTES));
+		return line ? { error: line } : {};
+	} catch {
+		return {};
+	}
+}
 
 function main() {
 	const configPath = process.argv[2];
@@ -40,7 +89,18 @@ function main() {
 	/** @type {import("../src/core/types.mjs").HostConfig|null} */
 	const config = readJson(configPath, null);
 	if (!config) failEarly(`pty-runner: cannot read config ${configPath}`);
+	// New ownership protocol (issue #70): instance-scoped config selects the fenced
+	// path. Legacy configs (no instanceId) keep the historical behavior unchanged.
+	if (config.instanceId) {
+		// A mid-flight throw in ownedMain must still terminate the process — the
+		// runner is detached with ignored stdio; an unhandled rejection would hang it.
+		ownedMain(config).catch(() => process.exit(1));
+		return;
+	}
+	legacyMain(config);
+}
 
+function legacyMain(config) {
 	const socketPath = P.controlSocketPath(config.root, config.viewId);
 	const screenLog = P.screenLogPath(config.root, config.viewId);
 	// Optional per-install cap override from launch prefs (screenLogMaxSize).
@@ -197,7 +257,9 @@ function main() {
 		// After a crash the handler already persisted "failed" and broadcast
 		// exit; this callback must not overwrite that state.
 		if (!crashed) {
-			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null });
+			// Attribute only a NATURAL abnormal exit (issue #90): after a deliberate
+			// stop (shutdownStarted) the child was killed by us — no error line.
+			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null, ...(shutdownStarted ? {} : attributedExitError(exitCode, screenLog)) });
 			editorEmpty = null;
 			broadcast({ type: "editor_state", empty: null });
 			broadcast({ type: "exit", exitCode });
@@ -323,6 +385,533 @@ function main() {
 	process.on("SIGINT", () => { void shutdown(); });
 }
 
+/**
+ * New-protocol host runner (issue #70).
+ *
+ * Runs only for instance-scoped configs. The lifecycle is fenced by an
+ * `instanceId` owner token and the per-view `host-start` lease:
+ *   lease → ownership decision → bind UNIQUE endpoint → publish runner identity
+ *   → spawn child → publish ready → release lease → heartbeat.
+ * All exits funnel through finishHost(), which writes only while the instance
+ * still owns host.json and unlinks only the exact socket inode it bound.
+ * @param {import("../src/core/types.mjs").HostConfig & { instanceId: string }} config
+ */
+async function ownedMain(config) {
+	if (!config.socketPath) failEarly("pty-runner: owned config missing socketPath");
+	const socketPath = config.socketPath;
+	const screenLog = P.screenLogPath(config.root, config.viewId);
+	const screenLogMaxBytes =
+		Number.isFinite(config.screenLogMaxBytes) && config.screenLogMaxBytes > 0
+			? Math.floor(config.screenLogMaxBytes)
+			: undefined;
+	const screenLogLimits = { maxBytes: screenLogMaxBytes };
+	let screenLogBytes = reconcileScreenLog(screenLog, screenLogLimits);
+
+	/** @type {Set<import("node:net").Socket>} */
+	const clients = new Set();
+	let childPid = null;
+	let child = null;
+	let exitCode = null;
+	let childExited = false;
+	let resolveChildExit;
+	const childExitPromise = new Promise((resolve) => {
+		resolveChildExit = resolve;
+	});
+	/** {dev,ino} recorded at bind time; cleanup unlinks only this exact inode. */
+	let boundSocketIdentity = null;
+	/** Set once THIS process published its runner identity into the record —
+	 * only then may finishHost write host state. A same-instance duplicate that
+	 * dies at listen (EADDRINUSE) shares the fencing token but never took the
+	 * record, so it must leave the winner's state untouched (issue #70). */
+	let claimedRecord = false;
+	let shutdownStarted = false;
+	/** Authoritative child editor emptiness (issue #68); null = unknown. */
+	let editorEmpty = null;
+	/** In-memory snapshot of the owned host record, refreshed on every owned write. */
+	let host = readHost(config.root, config.viewId);
+	/** @type {{ token: string, touch(): boolean, isOwner(): boolean, release(): boolean } | null} */
+	let startLease = null;
+	let startTouchTimer = null;
+	let heartbeatTimer = null;
+	let server = null;
+	/** Service-input ack dedup: requestId → true. FIFO-capped at
+	 *  HOST_ACK_DEDUP_MAX. Interactive UI keystrokes (no requestId) bypass it. */
+	const ackedRequestIds = new Map();
+	/** Last {cols, rows} held while the child does not exist yet; applied when
+	 *  ready is published (issue #70 §6.3 starting protocol). */
+	let cachedResize = null;
+
+	const diag = (code, message, details) => {
+		try {
+			appendDiagnostic(config.root, config.viewId, {
+				source: "runner",
+				code,
+				message,
+				...(details ? { details } : {}),
+			});
+		} catch { /* best effort */ }
+	};
+	const broadcast = (msg) => {
+		const line = JSON.stringify(msg) + "\n";
+		for (const c of clients) {
+			try { c.write(line); } catch { /* best effort */ }
+		}
+	};
+	/** Owner-fenced host write; refreshes the in-memory snapshot. */
+	const ownedUpdate = (mutate) => {
+		const result = updateOwnedHost(config.root, config.viewId, config.instanceId, (cur) => {
+			const next = mutate(cur);
+			return { ...next, lastSeenAt: Date.now(), attachedClients: clients.size };
+		});
+		if (result.updated && result.host) host = result.host;
+		return result;
+	};
+	const isOwnerNow = () => {
+		const h = readHost(config.root, config.viewId);
+		return Boolean(h && h.instanceId === config.instanceId);
+	};
+	const releaseStartLease = () => {
+		if (startTouchTimer) {
+			clearInterval(startTouchTimer);
+			startTouchTimer = null;
+		}
+		const lease = startLease;
+		startLease = null;
+		try { lease?.release(); } catch { /* best effort */ }
+	};
+
+	function waitForChildExit(timeoutMs) {
+		if (childExited) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			let settled = false;
+			let timer;
+			const finish = (exited) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				resolve(exited);
+			};
+			timer = setTimeout(() => finish(false), timeoutMs);
+			childExitPromise.then(() => finish(true));
+		});
+	}
+
+	/** Reasons that finalize as `failed` rather than `exited`. */
+	const FAILED_REASONS = new Set(["server_error", "child_error", "crash", "child_spawn_failed", "endpoint_busy"]);
+
+	/**
+	 * Idempotent unified finish: fenced terminal write, bounded server close,
+	 * child exit with escalation, inode-owned socket cleanup, config cleanup.
+	 * @param {string} reason
+	 * @param {number|null} [requestedExitCode]
+	 */
+	async function finishHost(reason, requestedExitCode = null) {
+		if (shutdownStarted) return;
+		shutdownStarted = true;
+		if (heartbeatTimer) {
+			clearInterval(heartbeatTimer);
+			heartbeatTimer = null;
+		}
+		// Only the runner that actually claimed the record writes terminal state; a
+		// superseded owner (or a duplicate that never claimed) never writes.
+		if (claimedRecord && reason !== "owner_lost" && isOwnerNow()) {
+			ownedUpdate((cur) => ({ ...cur, state: "stopping", stopReason: reason }));
+			broadcast({ type: "status", status: host });
+		}
+		try { broadcast({ type: "exit", exitCode: requestedExitCode ?? exitCode ?? 0 }); } catch { /* best effort */ }
+		for (const c of clients) {
+			try { c.destroy(); } catch { /* best effort */ }
+		}
+		clients.clear();
+		// Bounded server close (1s): never let a stuck client block cleanup.
+		await new Promise((resolve) => {
+			if (!server) return resolve();
+			let settled = false;
+			const done = () => {
+				if (!settled) {
+					settled = true;
+					resolve();
+				}
+			};
+			const timer = setTimeout(done, 1000);
+			server.close(() => {
+				clearTimeout(timer);
+				done();
+			});
+		});
+		if (child && !childExited) {
+			killChild(child, childPid, "SIGTERM");
+			if (!(await waitForChildExit(4000)) && !childExited) {
+				killChild(child, childPid, "SIGKILL");
+				await waitForChildExit(1000);
+			}
+		}
+		if (claimedRecord && reason !== "owner_lost" && isOwnerNow()) {
+			const failed = FAILED_REASONS.has(reason);
+			ownedUpdate((cur) => ({
+				...cur,
+				state: failed ? "failed" : "exited",
+				endedAt: Date.now(),
+				exitCode: requestedExitCode ?? exitCode ?? 0,
+				childPid: null,
+				readyAt: null,
+				stopRequestedAt: null,
+				stopReason: reason,
+				// Attribute abnormal NATURAL child exits only (issue #90): reason
+				// "child_exit" with a non-zero code. Stops ("signal") and crashes
+				// have their own attribution (stopReason / crash finalize), and a
+				// SIGTERM'd healthy child must not capture a junk error line.
+				...(reason === "child_exit" && cur.error == null
+					? attributedExitError(requestedExitCode ?? exitCode ?? 0, screenLog)
+					: {}),
+			}));
+		}
+		// Endpoint cleanup: only the exact inode this instance bound.
+		if (process.platform !== "win32" && boundSocketIdentity) {
+			try {
+				const st = statSync(socketPath);
+				if (ownsEndpoint(boundSocketIdentity, { dev: st.dev, ino: st.ino })) {
+					try { unlinkSync(socketPath); } catch { /* best effort */ }
+				}
+			} catch { /* path gone — nothing to clean */ }
+		}
+		// Best-effort config cleanup (instance-scoped file only).
+		try {
+			if (config.configPath && config.instanceId && config.configPath.includes(config.instanceId)) {
+				unlinkSync(config.configPath);
+			}
+		} catch { /* best effort */ }
+		releaseStartLease();
+		process.exit(requestedExitCode ?? exitCode ?? 0);
+	}
+
+	// Bounded finish: a mid-finish throw must still exit the process (the runner
+	// is detached; an unhandled rejection inside finishHost would otherwise hang).
+	const finish = (reason, requestedExitCode = null) => {
+		finishHost(reason, requestedExitCode).catch(() => process.exit(1));
+	};
+
+	process.on("SIGTERM", () => { finish("signal"); });
+	process.on("SIGINT", () => { finish("signal"); });
+	process.on("uncaughtException", (err) => {
+		process.removeAllListeners("uncaughtException");
+		const message = err instanceof Error ? err.message : String(err);
+		diag("runner_crash", message, { stack: err instanceof Error ? err.stack : undefined });
+		// Crash finalize is owner-fenced via the expected-instance path in
+		// finalizeHostCrash: a superseded owner must not clobber the replacement's
+		// record (it records host_crash_owner_changed instead of writing).
+		host = finalizeHostCrash(config.root, config.viewId, host, err, { expectedInstanceId: config.instanceId });
+		finish("crash", 1);
+	});
+
+	// 1. Take the per-view host-start lease — the launch transaction boundary.
+	try {
+	startLease = acquireOwnedViewLock(config.root, config.viewId, "host-start", {
+			waitMs: HOST_RUNNER_LOCK_WAIT_MS,
+			identity: { pid: process.pid, startToken: captureStartToken(process.pid) },
+		});
+	} catch (err) {
+		diag("host_start_lock_timeout", err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	startTouchTimer = setInterval(() => {
+		try { startLease?.touch(); } catch { /* best effort */ }
+	}, HEARTBEAT_MS);
+	startTouchTimer.unref?.();
+
+	// 2. Ownership decision inside the lease: never write host.json on the yield paths.
+	const current = readHost(config.root, config.viewId);
+	if (shouldYieldRunner({ host: current, instanceId: config.instanceId })) {
+		diag("host_start_yielded", "host record belongs to another active instance", { recordInstance: current?.instanceId ?? null });
+		releaseStartLease();
+		process.exit(0);
+	}
+	if (!current || current.instanceId !== config.instanceId) {
+		diag("host_start_stale_record", "no matching host claim for this instance", { recordInstance: current?.instanceId ?? null });
+		releaseStartLease();
+		process.exit(0);
+	}
+	// Own-terminal record: this instance already finished once (e.g. the prior
+	// runner of the SAME instance exited after claiming). Continuing would
+	// re-publish exited→starting and re-deliver initialPrompt — exit instead.
+	if (current.state === "exited" || current.state === "failed") {
+		diag("host_start_own_terminal", "host record for this instance is already terminal");
+		releaseStartLease();
+		process.exit(0);
+	}
+	if (current.state === "stopping" || current.stopRequestedAt != null) {
+		diag("host_start_revoked", "host claim was revoked before this runner started");
+		releaseStartLease();
+		process.exit(0);
+	}
+	host = current;
+
+	// 3. Bind the per-instance endpoint. NO unlink: the path is unique to this
+	//    instance; an occupied path means someone else owns it.
+	const listenOutcome = await new Promise((resolveListen) => {
+		const onError = (err) => resolveListen({ ok: false, error: err });
+		// Probe connections (clientId:"probe" hello) must not write host.json: the
+		// attach resolver's 150ms probe loop would amplify fenced writes and flip
+		// attachedEver with no client ever attached (CR round-1 finding 3).
+		const probeSockets = new WeakSet();
+		server = createServer((socket) => {
+			clients.add(socket);
+			socket.write(JSON.stringify({ type: "hello", status: host, editorEmpty }) + "\n");
+			broadcast({ type: "status", status: host });
+			let buffer = "";
+			socket.on("data", (chunk) => {
+				buffer += chunk.toString("utf8");
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) handleClientLine(line, socket);
+			});
+			socket.on("close", () => {
+				clients.delete(socket);
+				if (probeSockets.has(socket)) return;
+				// Merge into the live record (a stale closure spread here erases a
+				// concurrent revoke — final review finding 2).
+				ownedUpdate((cur) => ({ ...cur }));
+			});
+			socket.on("error", () => {
+				clients.delete(socket);
+				if (probeSockets.has(socket)) return;
+				ownedUpdate((cur) => ({ ...cur }));
+			});
+			socket.markProbe = () => probeSockets.add(socket);
+		});
+		server.once("error", onError);
+		server.listen(socketPath, () => {
+			server?.removeListener("error", onError);
+			resolveListen({ ok: true });
+		});
+	});
+	if (!listenOutcome.ok) {
+		diag("host_endpoint_busy", listenOutcome.error instanceof Error ? listenOutcome.error.message : String(listenOutcome.error));
+		await finishHost("endpoint_busy", 1);
+		return;
+	}
+	server.on("error", (err) => {
+		diag("server_error", err instanceof Error ? err.message : String(err));
+		finish("server_error", 1);
+	});
+	// POSIX: record the exact inode we bound — cleanup matches dev+ino.
+	if (process.platform !== "win32") {
+		try {
+			const st = statSync(socketPath);
+			boundSocketIdentity = { dev: st.dev, ino: st.ino };
+		} catch { /* without the identity, cleanup degrades to no-op */ }
+	}
+
+	// 4. Publish runner identity while still holding the lease.
+	const claimedSelf = ownedUpdate((cur) => ({
+		...cur,
+		runnerPid: process.pid,
+		runnerIdentity: { pid: process.pid, startToken: captureStartToken(process.pid) },
+		runnerSpawnedAt: cur.runnerSpawnedAt ?? Date.now(),
+		state: cur.state === "alive" ? "alive" : "starting",
+	}));
+	if (!claimedSelf.updated) {
+		await finishHost("owner_lost", 0);
+		return;
+	}
+	claimedRecord = true;
+	broadcast({ type: "status", status: host });
+
+	// Test seam (issue #70 Task 8): a config-level delay between publishing the
+	// runner identity and spawning the child creates a REAL starting window
+	// (endpoint accepting, child null) so the starting protocol is testable.
+	// Only host configs written by tests set this env; the service never does.
+	const spawnDelayMs = Number(config.env?.AGENT_BOARD_TEST_SPAWN_DELAY_MS || 0);
+	if (spawnDelayMs > 0) await new Promise((r) => { setTimeout(r, spawnDelayMs).unref?.(); });
+
+	// 5. Spawn the child — only after the endpoint is bound and owned.
+	const args = [...config.piArgsPrefix, "--session", config.sessionFile];
+	if (config.model) args.push("--model", config.model);
+	if (config.thinkingLevel) args.push("--thinking", config.thinkingLevel);
+	if (config.tools) args.push("--tools", config.tools);
+	if (config.initialPrompt) args.push(encodePromptForCliArg(config.initialPrompt));
+	const env = {
+		...process.env,
+		...(config.env || {}),
+		AGENT_BOARD_ROOT: config.root,
+		AGENT_BOARD_VIEW_ID: config.viewId,
+		AGENT_BOARD_CHILD: "1",
+		AGENT_BOARD_HOSTED: "pty",
+		// Legacy names are exported too so older child extension builds still behave.
+		AGENT_VIEW_ROOT: config.root,
+		AGENT_VIEW_VIEW_ID: config.viewId,
+		AGENT_VIEW_CHILD: "1",
+		AGENT_VIEW_HOSTED: "pty",
+	};
+	try {
+		child = spawnInteractive(config.piCommand, args, {
+			cwd: config.cwd,
+			env,
+			cols: host.cols,
+			rows: host.rows,
+			allowPipeFallback: config.env?.AGENT_BOARD_ALLOW_PIPE_FALLBACK === "1" || config.env?.AGENT_VIEW_ALLOW_PIPE_FALLBACK === "1",
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		diag("child_spawn_failed", message);
+		markRowFailed(config.root, config.viewId, `PTY host failed: ${message}`);
+		await finishHost("child_spawn_failed", 1);
+		return;
+	}
+	childPid = child.pid ?? null;
+	child.onData((data) => {
+		screenLogBytes = appendBoundedScreenLog(screenLog, data, screenLogBytes, screenLogLimits);
+		broadcast({ type: "output", data });
+	});
+	child.onExit((code) => {
+		childExited = true;
+		resolveChildExit?.();
+		exitCode = code ?? 0;
+		editorEmpty = null;
+		broadcast({ type: "editor_state", empty: null });
+		finish("child_exit", exitCode);
+	});
+	child.onError((err) => {
+		diag("child_error", err instanceof Error ? err.message : String(err));
+		finish("child_error", 1);
+	});
+
+	// 6. Re-check ownership after the child exists, then publish ready.
+	const ready = ownedUpdate((cur) => ({
+		...cur,
+		childPid,
+		childIdentity: { pid: childPid, startToken: captureStartToken(childPid) },
+		childSpawnedAt: Date.now(),
+		state: "alive",
+		readyAt: Date.now(),
+	}));
+	if (!ready.updated) {
+		// Superseded between spawn and ready: never publish; take the child down.
+		killChild(child, childPid, "SIGTERM");
+		const revoked = readHost(config.root, config.viewId)?.stopRequestedAt != null;
+		await finishHost(revoked ? "host_start_revoked" : "owner_lost", 0);
+		return;
+	}
+	broadcast({ type: "status", status: host });
+
+	// A starting-window resize cannot be applied at spawn-return nor at first
+	// output: the child node process is still bootstrapping and a SIGWINCH
+	// landing in that window is silently lost (pending-signal race, observed
+	// empirically). Defer the apply until the child has had time to finish
+	// bootstrapping; one-shot, best-effort, superseded by any newer direct
+	// resize (which clears the cache).
+	if (cachedResize) {
+		const applyHeld = setTimeout(() => {
+			if (!cachedResize || !child || shutdownStarted) return;
+			try { child.resize(cachedResize.cols, cachedResize.rows); } catch { /* best effort */ }
+			notifyChildResize(childPid);
+			cachedResize = null;
+		}, 500);
+		applyHeld.unref?.();
+	}
+
+	// 7. Launch transaction complete — hand the start lease back.
+	releaseStartLease();
+
+	// 8. Heartbeat: watch the owner record; loss or revoke routes to finishHost.
+	heartbeatTimer = setInterval(() => {
+		const h = readHost(config.root, config.viewId);
+		if (!h || h.instanceId !== config.instanceId) {
+			finish("owner_lost", 0);
+			return;
+		}
+		if (h.stopRequestedAt != null) {
+			finish("revoked", 0);
+			return;
+		}
+		const hb = ownedUpdate((cur) => ({ ...cur }));
+		// Plain host-meta lease contention returns {updated:false, ownerChanged:false}
+		// — transient, retry next tick (store.mjs contract). Only a confirmed
+		// ownership change tears the session down (CR round-1 finding 1).
+		if (hb.ownerChanged) finish("owner_lost", 0);
+	}, HEARTBEAT_MS);
+	heartbeatTimer.unref?.();
+
+	/** Client commands with the starting protocol (issue #70 §6.3): while the
+	 *  child does not exist, service inputs answer host_starting, resizes are
+	 *  held, and interactive keystrokes are dropped safely; once ready,
+	 *  requestId-tagged inputs ack with an in-process dedup table. */
+	function handleClientLine(line, socket) {
+		if (!line.trim()) return;
+		let msg;
+		try { msg = JSON.parse(line); } catch { return send(socket, { type: "error", message: "invalid json" }); }
+		switch (msg.type) {
+			case "hello":
+				// Probe handshakes (host-probe.mjs) are read-only: mark the socket so
+				// close/error skip the merge write, and never flip attachedEver
+				// (CR round-1 finding 3). Real clients record attachedEver here —
+				// deferred from connect time, which cannot distinguish them yet.
+				if (msg.clientId === "probe") {
+					socket.markProbe?.();
+				} else {
+					ownedUpdate((cur) => ({ ...cur, attachedEver: true }));
+				}
+				send(socket, { type: "hello", status: host, editorEmpty });
+				break;
+			case "input": {
+				if (typeof msg.data !== "string") break;
+				if (typeof msg.requestId !== "string" || !msg.requestId) {
+					// Interactive UI keystrokes: fire-and-forget, no ack protocol.
+					if (child) child.write(msg.data);
+					break;
+				}
+				if (!child) {
+					send(socket, { type: "error", code: "host_starting", requestId: msg.requestId });
+					break;
+				}
+				if (ackedRequestIds.has(msg.requestId)) {
+					send(socket, { type: "input_ack", requestId: msg.requestId });
+					break;
+				}
+				child.write(msg.data);
+				ackedRequestIds.set(msg.requestId, true);
+				if (ackedRequestIds.size > HOST_ACK_DEDUP_MAX) {
+					ackedRequestIds.delete(ackedRequestIds.keys().next().value);
+				}
+				send(socket, { type: "input_ack", requestId: msg.requestId });
+				break;
+			}
+			case "resize": {
+				const cols = clampInt(msg.cols, 20, 300, host.cols);
+				const rows = clampInt(msg.rows, 5, 120, host.rows);
+				if (child) {
+					child.resize(cols, rows);
+					notifyChildResize(childPid);
+					cachedResize = null;
+				} else {
+					cachedResize = { cols, rows };
+				}
+				ownedUpdate((cur) => ({ ...cur, cols, rows }));
+				break;
+			}
+			case "interrupt":
+				if (child) child.write("\x1b");
+				break;
+			case "terminate":
+				// Single exit path: finishHost carries the SIGTERM→4s→SIGKILL ladder,
+				// so a SIGTERM-immune child still terminates within a bounded window.
+				finish("terminated", 0);
+				break;
+			case "detach":
+				socket.end();
+				break;
+			case "get_status":
+				send(socket, { type: "status", status: host });
+				break;
+			case "editor_state": {
+				editorEmpty = typeof msg.empty === "boolean" ? msg.empty : null;
+				broadcast({ type: "editor_state", empty: editorEmpty });
+				break;
+			}
+		}
+	}
+}
+
 function spawnInteractive(command, args, opts) {
 	ensureNodePtySpawnHelperExecutable(requireForPty);
 	if (pty?.spawn) {
@@ -388,12 +977,46 @@ function killChild(child, pid, signal = "SIGTERM") {
 	try { child.kill(signal); } catch {}
 }
 
+/**
+ * node-pty's TIOCSWINSZ updates the kernel tty size, but the automatic
+ * SIGWINCH to the pty's foreground group is NOT reliably delivered when the
+ * runner itself is a detached session (empirically verified on Linux: the
+ * child's kernel size is correct, its signal handler never fires, and a
+ * direct kill delivers instantly). Real TUI children poll or handle SIGWINCH
+ * — an explicit best-effort signal is harmless for them and makes resize
+ * deterministic for every child. POSIX only.
+ * @param {number|null} pid
+ */
+function notifyChildResize(pid) {
+	if (process.platform === "win32" || !pid) return;
+	try { process.kill(pid, "SIGWINCH"); } catch { /* best effort */ }
+}
+
 function clampInt(value, min, max, fallback) {
 	const n = Number(value);
 	if (!Number.isFinite(n)) return fallback;
 	return Math.max(min, Math.min(max, Math.floor(n)));
 }
 
+/** POSIX process start token — /proc/<pid>/stat field 22 (starttime), stable
+ *  across exec(2). Recorded in published identities so service-side recovery
+ *  (issue #70 Task 11) can tell an owned-live pid from a reused one; null on
+ *  failure or non-Linux platforms. */
+function captureStartToken(pid) {
+	if (process.platform !== "linux" || !pid) return null;
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		// comm (field 2) may contain spaces and parens — fields resume AFTER the
+		// last ')'. fields[0] is state (field 3) → starttime (field 22) is [19].
+		const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trimStart();
+		const fields = afterComm.split(/\s+/);
+		const startTime = fields[19];
+		return startTime ?? null;
+	} catch {
+		return null;
+	}
+}
+
 
 function markRowFailed(root, viewId, message) {
 	const now = Date.now();

package/runner/state-runner.mjs

@@ -79,6 +79,9 @@ function sanitizedEnv() {
 	delete env.AGENT_VIEW_VIEW_ID;
 	delete env.AGENT_BOARD_HOSTED;
 	delete env.AGENT_VIEW_HOSTED;
+	// Board-spawned classifier workers must not arm the warm-host sweeper
+	// (they share the board root with real hosts).
+	env.AGENT_BOARD_NO_SWEEP = "1";
 	return env;
 }