@zhuxixi/pi-agent-board 0.5.2 → 0.6.0

package/src/core/launch.mjs

@@ -55,7 +55,9 @@ export function launchRun(root, config, opts) {
  * @returns {{ pid: number|null, configPath: string }}
  */
 export function launchHost(root, config, opts) {
-	const configPath = P.hostConfigPath(root, config.viewId);
+	// Instance-specific config path wins when present (issue #70: concurrent
+	// launches must not share the fixed host-config.json); legacy callers keep it.
+	const configPath = config.configPath ?? P.hostConfigPath(root, config.viewId);
 	atomicWriteJson(configPath, config);
 
 	const node = opts.node ?? resolveNode();

package/src/core/locks.mjs

@@ -10,9 +10,11 @@
  *   MAX_ENV_ATTEMPTS quick retries — each retry re-runs ensureDir so a parent
  *   deleted mid-acquisition self-heals — then throw LOCK_TIMEOUT. Never spin.
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { ensureDir } from "./atomic.mjs";
+import { isAlive } from "./pid.mjs";
 import * as P from "./paths.mjs";
 
 const DEFAULT_STALE_MS = 30_000;
@@ -134,3 +136,196 @@ function releaseLock(lockPath, fs) {
 		/* best effort */
 	}
 }
+
+// ---- owner-safe leases (issue #70) ----------------------------------------
+
+/** Lease fs = lock fs + rename (candidate publish + quarantine reclaim). */
+const defaultLeaseFs = Object.freeze({ ...defaultLocksFs, renameSync });
+/** Max stale-reclaim → republish rounds inside a single acquire attempt. */
+const MAX_LEASE_RECLAIM_ATTEMPTS = 3;
+
+/**
+ * A token-fenced lease over the view-lock directory. Every operation re-reads
+ * owner.json and only acts while it still carries this lease's token, so a
+ * superseded owner can never touch — heartbeat or delete — the current owner's
+ * lock. Unlike withFileLockSync, a held lock is never stolen by age alone; it
+ * can only be reclaimed when its recorded owner process is provably dead.
+ * @typedef {Object} Lease
+ * @property {string} token
+ * @property {() => boolean} touch
+ * @property {() => boolean} isOwner
+ * @property {() => boolean} release
+ */
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} name
+ * @param {{ waitMs?: number, identity?: object|null, fs?: Partial<typeof defaultLeaseFs>, clock?: () => number, isProcessDead?: (pid: number) => boolean }} [opts]
+ * @returns {Lease}
+ * @throws {Error & { code: "LOCK_TIMEOUT" }} when the lock is still held after waitMs
+ */
+export function acquireOwnedViewLock(root, viewId, name, opts = {}) {
+	const lockPath = P.viewLockPath(root, viewId, name);
+	const deadline = Date.now() + Math.max(0, Number(opts.waitMs ?? 0));
+	for (;;) {
+		const attempt = attemptAcquireLease(lockPath, opts);
+		if (typeof attempt !== "string") return attempt;
+		if (Date.now() >= deadline) throw lockError(lockPath, `lease not acquired (${attempt})`);
+		sleep(WAIT_TICK_MS);
+	}
+}
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} name
+ * @param {{ identity?: object|null, fs?: Partial<typeof defaultLeaseFs>, clock?: () => number, isProcessDead?: (pid: number) => boolean }} [opts]
+ * @returns {{ acquired: true, lease: Lease } | { acquired: false, reason: "busy"|"blocked" }}
+ */
+export function tryAcquireOwnedViewLock(root, viewId, name, opts = {}) {
+	const attempt = attemptAcquireLease(P.viewLockPath(root, viewId, name), opts);
+	if (typeof attempt === "string") return { acquired: false, reason: attempt };
+	return { acquired: true, lease: attempt };
+}
+
+/**
+ * Single-shot acquire round: publish a complete candidate lock (owner.json
+ * written BEFORE the lock path exists) via atomic rename, and on contention
+ * either reclaim a provably-dead owner's lock via quarantine or report.
+ * @param {string} lockPath
+ * @param {{ identity?: object|null, fs?: Partial<typeof defaultLeaseFs>, clock?: () => number, isProcessDead?: (pid: number) => boolean }} opts
+ * @returns {Lease | "busy" | "blocked"}
+ */
+function attemptAcquireLease(lockPath, opts) {
+	const fs = { ...defaultLeaseFs, ...(opts.fs ?? {}) };
+	const now = opts.clock ?? Date.now;
+	const isProcessDead = opts.isProcessDead ?? ((pid) => !isAlive(pid));
+	const identity = opts.identity ?? null;
+	for (let attempt = 0; attempt < MAX_LEASE_RECLAIM_ATTEMPTS; attempt++) {
+		const token = randomBytes(16).toString("hex");
+		const candidate = `${lockPath}.candidate.${token}`;
+		ensureDir(path.dirname(lockPath));
+		try {
+			// Candidate dir is unique per token; a rename publishes the COMPLETE
+			// record atomically — no observer can see a lock without owner.json.
+			fs.mkdirSync(candidate);
+			fs.writeFileSync(
+				path.join(candidate, "owner.json"),
+				JSON.stringify({ token, pid: process.pid, identity, startedAt: now() }),
+				"utf8",
+			);
+			fs.renameSync(candidate, lockPath);
+			return makeLease(lockPath, token, fs, now);
+		} catch (err) {
+			try { fs.rmSync(candidate, { recursive: true, force: true }); } catch { /* best effort */ }
+			const code = err && err.code;
+			if (code !== "EEXIST" && code !== "ENOTEMPTY") throw err;
+			const verdict = reclaimOrBlock(lockPath, token, fs, isProcessDead);
+			if (verdict !== true) return verdict;
+			// Reclaimed a dead owner's lock — retry the publish on the next round.
+		}
+	}
+	return "busy";
+}
+
+/**
+ * Decide whether an existing lock may be reclaimed. Only a lock whose
+ * owner.json carries a usable identity (pid + startToken) AND whose pid is
+ * provably dead is reclaimable; anything corrupt, unreadable, or live is
+ * never deleted. Reclaim quarantines via rename first so a concurrent winner
+ * can only ever delete the directory it itself renamed.
+ * @param {string} lockPath
+ * @param {string} token the caller's own token (names the quarantine dir)
+ * @param {typeof defaultLeaseFs} fs
+ * @param {(pid: number) => boolean} isProcessDead
+ * @returns {true | "busy" | "blocked"}
+ */
+function reclaimOrBlock(lockPath, token, fs, isProcessDead) {
+	let owner;
+	try {
+		owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf8"));
+	} catch {
+		return "blocked";
+	}
+	const pid = Number(owner?.identity?.pid ?? 0);
+	if (!Number.isFinite(pid) || pid <= 0 || typeof owner?.identity?.startToken !== "string") return "blocked";
+	if (!isProcessDead(pid)) return "busy";
+	const inspectedToken = typeof owner?.token === "string" ? owner.token : null;
+	if (inspectedToken === null) return "blocked";
+	const quarantine = `${lockPath}.reclaim.${token}`;
+	try {
+		fs.renameSync(lockPath, quarantine);
+	} catch {
+		// Someone else released/reclaimed concurrently — plain contention.
+		return "busy";
+	}
+	// Verify we quarantined exactly the lock we inspected: a concurrent winner
+	// may have reclaimed the dead owner and published a fresh lock at lockPath
+	// between our read and this rename. If so, restore it and report contention
+	// instead of deleting a successor's lock.
+	let quarantinedToken = null;
+	try {
+		quarantinedToken = JSON.parse(fs.readFileSync(path.join(quarantine, "owner.json"), "utf8"))?.token ?? null;
+	} catch { /* unreadable quarantine content */ }
+	if (quarantinedToken !== inspectedToken) {
+		try { fs.renameSync(quarantine, lockPath); } catch { /* best effort restore */ }
+		return "busy";
+	}
+	try { fs.rmSync(quarantine, { recursive: true, force: true }); } catch { /* best effort */ }
+	return true;
+}
+
+/**
+ * @param {string} lockPath
+ * @param {string} token
+ * @param {typeof defaultLeaseFs} fs
+ * @param {() => number} now
+ * @returns {Lease}
+ */
+function makeLease(lockPath, token, fs, now) {
+	const ownerPath = path.join(lockPath, "owner.json");
+	const heartbeatPath = path.join(lockPath, `heartbeat.${token}`);
+	const stillOwns = () => {
+		try {
+			return JSON.parse(fs.readFileSync(ownerPath, "utf8"))?.token === token;
+		} catch {
+			return false;
+		}
+	};
+	return {
+		token,
+		isOwner: () => stillOwns(),
+		touch() {
+			if (!stillOwns()) return false;
+			try {
+				// Heartbeat lives in a token-named file: old tokens can never
+				// overwrite the canonical owner record or a successor's heartbeat.
+				fs.writeFileSync(heartbeatPath, JSON.stringify({ at: now() }), "utf8");
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		release() {
+			if (!stillOwns()) return false;
+			try {
+				fs.rmSync(lockPath, { recursive: true, force: true });
+				return true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}
+
+/**
+ * Simulates a late release() from a superseded token. Exported so tests can
+ * prove old tokens can never delete a successor's lock.
+ * @visibleForTesting
+ * @param {string} root @param {string} viewId @param {string} name @param {string} token
+ * @returns {boolean}
+ */
+export function releaseWithToken(root, viewId, name, token) {
+	return makeLease(P.viewLockPath(root, viewId, name), token, defaultLeaseFs, Date.now).release();
+}

package/src/core/paths.mjs

@@ -5,6 +5,7 @@
  * The live default is `~/.pi/agent/agent-board/` (override with $AGENT_BOARD_ROOT;
  * legacy $AGENT_VIEW_ROOT is also honored for migration).
  */
+import { createHash } from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -38,6 +39,13 @@ export const statePath = (root, viewId) => path.join(viewDir(root, viewId), "sta
 export const hostPath = (root, viewId) => path.join(viewDir(root, viewId), "host.json");
 /** @param {string} root @param {string} viewId */
 export const hostConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "host-config.json");
+/**
+ * Per-instance host config path. Each host launch owns its own config file so a
+ * concurrent launch can never overwrite another instance's prompt/cwd/model (issue #70).
+ * @param {string} root @param {string} viewId @param {string} instanceId
+ */
+export const hostConfigPathFor = (root, viewId, instanceId) =>
+	path.join(viewDir(root, viewId), `host-config.${instanceId}.json`);
 /** @param {string} root @param {string} viewId */
 export const titleConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "title-config.json");
 /** @param {string} root @param {string} viewId */
@@ -63,6 +71,22 @@ export function controlSocketPathFor(platform, root, viewId) {
 }
 /** @param {string} root @param {string} viewId */
 export const controlSocketPath = (root, viewId) => controlSocketPathFor(process.platform, root, viewId);
+/**
+ * Per-instance control endpoint. Each new host instance binds its own socket/pipe,
+ * so a superseded runner can never unlink the current owner's endpoint (issue #70).
+ * win32 pipe names embed an 8-hex hash of the instanceId to stay under the 256-char limit.
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} instanceId
+ */
+export function hostEndpointPathFor(platform, root, viewId, instanceId) {
+	if (platform === "win32") {
+		const hash = createHash("sha256").update(String(instanceId)).digest("hex").slice(0, 8);
+		return `\\\\.\\pipe\\pi-agent-board-${viewId}-${hash}`;
+	}
+	return path.join(viewDir(root, viewId), `control.${instanceId}.sock`);
+}
 /** @param {string} root @param {string} viewId */
 export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId), "screen.log");
 /** @param {string} root @param {string} viewId */

package/src/core/store.mjs

@@ -5,6 +5,8 @@
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { atomicWriteJson, ensureDir, readJson } from "./atomic.mjs";
+import { sameHostOwner } from "./host-coordination.mjs";
+import { tryAcquireOwnedViewLock } from "./locks.mjs";
 import * as P from "./paths.mjs";
 import { isAlive } from "./pid.mjs";
 import { readCodeRefs, summarizeCodeRefs } from "./code-refs-store.mjs";
@@ -120,9 +122,159 @@ export function writeHost(root, host) {
 	atomicWriteJson(P.hostPath(root, host.viewId), host);
 }
 
-/** @param {string} root @param {string} viewId @param {number|null} pid */
-export function writeHostPid(root, viewId, pid) {
-	atomicWriteJson(P.hostPidPath(root, viewId), { pid, at: Date.now() });
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {number|null} pid
+ * @param {{ instanceId?: string, identity?: object|null }} [extra] merged into the mirror record
+ */
+export function writeHostPid(root, viewId, pid, extra) {
+	atomicWriteJson(P.hostPidPath(root, viewId), { pid, at: Date.now(), ...(extra ?? {}) });
+}
+
+/**
+ * Host states that represent an unreplaced claim: no replacement may be
+ * started while a host record is in one of these states (issue #70).
+ * @param {HostStatus|null} host
+ */
+function hostClaimActive(host) {
+	return Boolean(host && (host.state === "starting" || host.state === "alive" || host.state === "stopping"));
+}
+
+/**
+ * Atomically create the provisional `starting` host record for a new instance.
+ * The ONLY entry point allowed to move "no claim / reclaimable terminal state"
+ * into `starting` (issue #70). Refuses when an active claim exists or the
+ * host-meta lease is contended; the fresh record always nulls runner/child/
+ * ready/stop fields so no stale owner data survives the handover.
+ * @param {string} root
+ * @param {Partial<HostStatus> & { viewId: string, instanceId: string }} provisionalHost
+ * @param {{ heldStartLease?: unknown }} [opts] reserved for host-start lease nesting;
+ *   host-meta is always acquired independently here (short critical section).
+ * @returns {{ claimed: boolean, host: HostStatus|null }}
+ */
+export function claimHost(root, provisionalHost, opts = {}) {
+	const lock = tryAcquireOwnedViewLock(root, provisionalHost.viewId, "host-meta");
+	if (!lock.acquired) return { claimed: false, host: null };
+	try {
+		const existing = readHost(root, provisionalHost.viewId);
+		if (hostClaimActive(existing)) return { claimed: false, host: existing };
+		const now = Date.now();
+		/** @type {HostStatus} */
+		const record = {
+			version: 1,
+			viewId: provisionalHost.viewId,
+			mode: "pty",
+			instanceId: provisionalHost.instanceId,
+			configPath: provisionalHost.configPath ?? null,
+			socketPath: provisionalHost.socketPath ?? null,
+			claimAt: provisionalHost.claimAt ?? now,
+			claimPid: provisionalHost.claimPid ?? null,
+			claimIdentity: provisionalHost.claimIdentity ?? null,
+			// A fresh claim owns nothing yet: force-clear every field a superseded
+			// instance might have left behind.
+			runnerPid: null,
+			runnerIdentity: null,
+			runnerSpawnedAt: null,
+			childPid: null,
+			childIdentity: null,
+			childSpawnedAt: null,
+			readyAt: null,
+			stopRequestedAt: null,
+			revokeToken: null,
+			stopReason: null,
+			state: "starting",
+			startedAt: provisionalHost.claimAt ?? now,
+			lastSeenAt: now,
+			endedAt: null,
+			exitCode: null,
+			error: null,
+			cols: provisionalHost.cols ?? 120,
+			rows: provisionalHost.rows ?? 36,
+			attachedClients: 0,
+		};
+		writeHost(root, record);
+		// Mirror is best-effort; host.json is the authority for the new protocol.
+		try {
+			writeHostPid(root, provisionalHost.viewId, record.claimPid, {
+				instanceId: record.instanceId,
+				identity: record.claimIdentity,
+			});
+		} catch { /* best effort */ }
+		return { claimed: true, host: record };
+	} finally {
+		lock.lease.release();
+	}
+}
+
+/**
+ * Bounded contention retry for owner-fenced host writes (issue #70, PR #84 CI
+ * wave 2). Heartbeat/client-merge writes hold the host-meta lease for only a
+ * few milliseconds, but a one-shot acquire can land inside that window and
+ * return busy — a revoke or recovery write that silently no-ops is a real
+ * reliability bug, not just a test race. Both `busy` (live owner) and
+ * `blocked` (identity-less short hold — updateOwnedHost itself acquires
+ * host-meta without a reclaimable identity, so concurrent fenced writes look
+ * blocked to each other) are transient here: retry a few times with a short
+ * synchronous sleep before giving up. A genuinely orphaned host-meta lock
+ * (holder SIGKILLed mid-hold) survives the window and surfaces as retryable
+ * not-updated — never as ownership loss.
+ */
+const UPDATE_LOCK_BUSY_ATTEMPTS = 3;
+const UPDATE_LOCK_BUSY_SLEEP_MS = 20;
+
+/**
+ * Owner-fenced compare-and-write for host.json. Re-reads the view's record
+ * under the host-meta lease and only applies `mutate` while it still belongs
+ * to `expectedInstanceId`; a superseded instance's late heartbeat/crash/exit
+ * writes are rejected with `ownerChanged: true` and the current host (issue
+ * #70). Lease contention that survives the bounded retry returns not-updated
+ * with `ownerChanged: false` — callers treat that as retryable (heartbeats
+ * simply retry next tick; revokes/recovery re-attempt).
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} expectedInstanceId
+ * @param {(host: HostStatus) => HostStatus} mutate returns a new record
+ * @param {{ heldStartLease?: unknown, lockImpl?: typeof tryAcquireOwnedViewLock }} [opts]
+ *   heldStartLease is reserved for host-start lease nesting; lockImpl injects
+ *   the host-meta acquisition for deterministic contention tests.
+ * @returns {{ updated: boolean, ownerChanged: boolean, host: HostStatus|null }}
+ */
+export function updateOwnedHost(root, viewId, expectedInstanceId, mutate, opts = {}) {
+	const acquireHostMeta = opts.lockImpl ?? tryAcquireOwnedViewLock;
+	let lock;
+	for (let attempt = 0; ; attempt++) {
+		lock = acquireHostMeta(root, viewId, "host-meta");
+		if (lock.acquired) break;
+		// busy and blocked are both millisecond-scale holds for host-meta;
+		// neither is ownership information — only the fenced read below is.
+		if (attempt >= UPDATE_LOCK_BUSY_ATTEMPTS - 1) {
+			return { updated: false, ownerChanged: false, host: null };
+		}
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, UPDATE_LOCK_BUSY_SLEEP_MS);
+	}
+	try {
+		const host = readHost(root, viewId);
+		if (!host || !sameHostOwner(host, expectedInstanceId)) {
+			return { updated: false, ownerChanged: true, host };
+		}
+		const next = mutate(host);
+		// The mutate result must still belong to the expected instance: a buggy or
+		// hijacked callback that swaps the owner token is never written (issue #70).
+		if (!sameHostOwner(next, expectedInstanceId)) {
+			return { updated: false, ownerChanged: true, host };
+		}
+		writeHost(root, next);
+		try {
+			writeHostPid(root, viewId, next.runnerPid ?? null, {
+				instanceId: next.instanceId,
+				identity: next.runnerIdentity ?? null,
+			});
+		} catch { /* best effort */ }
+		return { updated: true, ownerChanged: false, host: next };
+	} finally {
+		lock.lease.release();
+	}
 }
 
 /** @param {string} root @param {string} viewId @returns {number|null} */
@@ -177,6 +329,8 @@ function mtime(dir) {
  * @property {ViewState|null} state
  * @property {boolean} alive  Whether the row's current run pid/foreground activity is alive.
  * @property {boolean} hostAlive Whether a PTY host/socket is alive and attachable.
+ * @property {boolean} hostActive Whether an unreplaced host claim exists (starting/alive/stopping).
+ * @property {boolean} hostReady Whether the host claims readiness (alive + readyAt); metadata hint only.
  * @property {HostStatus|null} host
  * @property {import("./types.mjs").ReviewSummary} [review]
  * @property {import("./types.mjs").DiagnosticSummary} [diagnostics]
@@ -202,9 +356,14 @@ export function loadRow(root, viewId) {
 	// poll, but foreground extension events mirror processState into state.json.
 	if (!alive && enrichedState?.processState === "alive") alive = true;
 	const host = readHost(root, viewId);
-	const hostPid = host?.runnerPid ?? readHostPid(root, viewId);
+	// New-protocol records carry an explicit runnerPid (null until spawn
+	// confirms); only legacy records without the property fall back to the
+	// host-pid mirror (issue #70).
+	const hostPid = host && Object.hasOwn(host, "runnerPid") ? host.runnerPid : readHostPid(root, viewId);
 	const hostAlive = Boolean(host && (host.state === "alive" || host.state === "starting") && isAlive(hostPid));
-	return { meta, state: enrichedState, alive, hostAlive, host, ...summaries };
+	const hostActive = Boolean(host && (host.state === "starting" || host.state === "alive" || host.state === "stopping"));
+	const hostReady = Boolean(hostActive && host.state === "alive" && host.readyAt != null);
+	return { meta, state: enrichedState, alive, hostAlive, hostActive, hostReady, host, ...summaries };
 }
 
 /** @param {string} root @param {string} viewId */

package/src/core/types.mjs

@@ -6,7 +6,7 @@
 /** Semantic (task) state of a row. @typedef {"queued"|"working"|"needs_input"|"idle"|"completed"|"failed"|"stopped"} SemanticState */
 /** Process/liveness state. @typedef {"alive"|"exited"} ProcessState */
 /** PTY host mode. @typedef {"json-runner"|"pty"} HostMode */
-/** PTY host liveness. @typedef {"starting"|"alive"|"exited"|"failed"} HostState */
+/** PTY host liveness. @typedef {"starting"|"alive"|"stopping"|"exited"|"failed"} HostState */
 /** How a run was kicked off. @typedef {"dispatch"|"reply"|"plan"|"plan_change"|"plan_approval"} RunKind */
 /** Worktree isolation mode for a row. @typedef {"off"|"worktree"} WorktreeMode */
 /** Diagnostic severity. @typedef {"info"|"warn"|"error"} DiagnosticLevel */
@@ -141,6 +141,19 @@ export const GROUP_LABELS = {
  * @property {number} rows
  * @property {number} attachedClients
  * @property {boolean} [attachedEver] Whether any client attached to this host.
+ * @property {string|null} [instanceId] Owner/fencing token for this host launch (issue #70).
+ * @property {string|null} [configPath] Per-instance config file this host was launched with.
+ * @property {number|null} [claimAt] When the provisional claim was written (epoch ms).
+ * @property {number|null} [claimPid] PID of the service process that wrote the claim.
+ * @property {{pid:number,startToken:string|null}|null} [claimIdentity] Launch-time identity of the claiming service process.
+ * @property {{pid:number,startToken:string|null}|null} [runnerIdentity] Stable identity of the runner process.
+ * @property {number|null} [runnerSpawnedAt] When the runner spawn was confirmed (null = not yet spawned).
+ * @property {{pid:number,startToken:string|null}|null} [childIdentity] Stable identity of the child Pi process.
+ * @property {number|null} [childSpawnedAt] When the child spawn was confirmed (null = not yet spawned).
+ * @property {number|null} [readyAt] Set only after endpoint bind + child creation; alive implies readyAt != null.
+ * @property {number|null} [stopRequestedAt] When a revoke was requested via the host record.
+ * @property {string|null} [revokeToken] Random token written by requestHostStop to fence duplicate revokes.
+ * @property {string|null} [stopReason] Human-readable reason recorded with the revoke.
  */
 
 /**
@@ -213,6 +226,9 @@ export const GROUP_LABELS = {
  * @property {number} cols
  * @property {number} rows
  * @property {number|null} screenLogMaxBytes per-view screen.log write cap; null = runner default
+ * @property {string|null} [instanceId] Owner/fencing token for this host launch (issue #70).
+ * @property {string|null} [configPath] Per-instance config file path; each launch owns its own so concurrent launches never share a config.
+ * @property {string|null} [socketPath] Per-instance control endpoint the spawned runner must bind.
  */
 
 /**

package/src/core/warm-host-sweeper.mjs

@@ -0,0 +1,150 @@
+/**
+ * Warm-host sweep reclaim (issue #75).
+ *
+ * Idle PTY hosts must not live forever: after detach the runner is a detached
+ * orphan that nothing else will reap (Windows has no parent-death cascade, and
+ * the dashboard host may exit without a cleanup hook). The design intent
+ * (AGENT_BOARD_WARM_HOST_TTL_MS / MAX_WARM_HOSTS) already exists in
+ * service.mjs pruneWarmHosts but only fires lazily on attach/prewarm/dispatch.
+ * This module extracts the pure eviction decision plus a periodic sweeper so
+ * the TTL actually runs.
+ */
+
+/** @param {import("./store.mjs").Row} row */
+export function hasPendingQuestions(row) {
+	return Array.isArray(row.state?.pendingQuestions) && row.state.pendingQuestions.length > 0;
+}
+
+/**
+ * Busy = an agent run is active (queued/working) or the session is waiting on
+ * user questions. Idle/completed/failed/stopped are never busy.
+ * @param {import("./store.mjs").Row} row
+ */
+export function isAgentBusy(row) {
+	const st = row.state?.semanticState;
+	return Boolean(row.alive && (st === "queued" || st === "working" || hasPendingQuestions(row)));
+}
+
+/**
+ * Pure eviction decision for warm PTY hosts. No IO, no env: every threshold is
+ * passed in so the logic is directly unit-testable.
+ *
+ * idle = host alive && !busy && no attached clients && not keepViewId.
+ * graceMs exempts freshly started hosts (attach handoff race: ensureHost has
+ * started a host but the client has not connected yet).
+ * TTL eviction runs first; survivors over maxWarm are evicted oldest-first by
+ * idleSince = max(state.lastActivityAt, host.startedAt) || meta.updatedAt (host-level
+ * idle counts from host start, so a stale lastActivityAt from a previous host
+ * incarnation never makes a fresh host look idle longer than it has been up).
+ *
+ * @param {Array<import("./store.mjs").Row>} rows
+ * @param {{ now: number, maxWarm: number, ttlMs: number, graceMs?: number, keepViewId?: string|null }} o
+ * @returns {{ ttlEvicted: string[], excessEvicted: string[] }} viewIds, ttl group first
+ */
+export function selectIdleHostsToEvict(rows, { now, maxWarm, ttlMs, graceMs = 0, keepViewId = null }) {
+	// Both-zero = eviction disabled entirely. Callers (service.pruneWarmHosts)
+	// may additionally early-return for the same reason.
+	if (maxWarm === 0 && ttlMs === 0) return { ttlEvicted: [], excessEvicted: [] };
+	const idle = [];
+	for (const row of rows) {
+		if (keepViewId != null && row.meta.id === keepViewId) continue;
+		if (!row.hostAlive) continue;
+		if (isAgentBusy(row)) continue;
+		if ((row.host?.attachedClients ?? 0) !== 0) continue;
+		const startedAt = row.host?.startedAt;
+		if (graceMs > 0 && startedAt != null && now - startedAt < graceMs) continue;
+		// Host-level idle counts from host start: a stale lastActivityAt from a
+		// previous host incarnation must not make a freshly prewarmed host look
+		// idle for longer than it has actually been up (issue #75 review #1).
+		const idleSince = Math.max(row.state?.lastActivityAt ?? 0, startedAt ?? 0) || row.meta.updatedAt;
+		idle.push({ id: row.meta.id, idleSince });
+	}
+	const ttlEvicted = [];
+	const survivors = [];
+	for (const it of idle) {
+		// Keep the historical semantics: ttlMs === 0 disables the ttl branch
+		// (only the maxWarm cap applies); both zero disables eviction entirely.
+		if (ttlMs > 0 && now - it.idleSince > ttlMs) ttlEvicted.push(it.id);
+		else survivors.push(it);
+	}
+	survivors.sort((a, b) => a.idleSince - b.idleSince);
+	const excess = Math.max(0, survivors.length - maxWarm);
+	return { ttlEvicted, excessEvicted: survivors.slice(0, excess).map((it) => it.id) };
+}
+
+/**
+ * Periodic sweeper for warm hosts. The interval timer is unref'd so it never
+ * holds the host pi's event loop open on exit. intervalMs <= 0 disables the
+ * periodic part; sweepNow() always works.
+ *
+ * stop() only stops the periodic timer: sweepNow() stays available afterwards
+ * (the lifecycle wiring calls sweepNow() again on shutdown/dispose). start()
+ * is idempotent and may restart the timer after a stop.
+ * @param {{ sweep: () => void, intervalMs: number }} o
+ */
+export function createWarmHostSweeper({ sweep, intervalMs }) {
+	let timer = null;
+	return {
+		active: true,
+		start() {
+			if (timer !== null) return;
+			if (intervalMs > 0) {
+				timer = setInterval(() => {
+					try { sweep(); } catch { /* best-effort */ }
+				}, intervalMs);
+				if (typeof timer.unref === "function") timer.unref();
+			}
+		},
+		sweepNow() {
+			try { sweep(); } catch { /* best-effort */ }
+		},
+		stop() {
+			if (timer !== null) {
+				clearInterval(timer);
+				timer = null;
+			}
+		},
+	};
+}
+
+/**
+ * Wire the sweeper to a host pi extension lifetime: sweep once on attach
+ * (reclaims hosts leaked by a previous host that died without cleanup), run
+ * periodically, and sweep again on session_shutdown (host pi exiting or the
+ * extension instance being reloaded for a session switch).
+ *
+ * Child pi processes (AGENT_BOARD_CHILD=1 / AGENT_VIEW_CHILD=1) must never
+ * sweep: they share the same board root and would terminate their own runner
+ * (suicide chain). They get a strict no-op.
+ *
+ * @param {{ on?: (event: any, fn: () => void) => any }} pi — any, not a narrower
+ *   string-keyed signature: pi's ExtensionAPI.on is a union of literal event-name
+ *   overloads and would otherwise fail structural assignment from TypeScript
+ *   callers (contravariant parameter check).
+ * @param {{ isHostedChild: boolean, sweep: () => void, intervalMs: number }} o
+ */
+export function attachWarmHostSweeper(pi, { isHostedChild, sweep, intervalMs }) {
+	// Child pi processes and board-spawned non-host workers must never sweep:
+	// children would terminate their own runner (suicide chain); workers
+	// (job/state runners set AGENT_BOARD_NO_SWEEP=1) would churn the shared root.
+	if (isHostedChild || process.env.AGENT_BOARD_NO_SWEEP === "1") {
+		return { active: false, dispose() {} };
+	}
+	const sweeper = createWarmHostSweeper({ sweep, intervalMs });
+	let shutdown = false;
+	const onShutdown = () => {
+		if (shutdown) return;
+		shutdown = true;
+		sweeper.sweepNow();
+		sweeper.stop();
+	};
+	pi.on?.("session_shutdown", onShutdown);
+	sweeper.start();
+	sweeper.sweepNow(); // 回收上一个宿主（可能非正常退出）遗留的 warm hosts
+	return {
+		active: true,
+		dispose() {
+			onShutdown();
+		},
+	};
+}