@zhuxixi/pi-agent-board 0.3.0

package/src/core/launch-options.mjs

@@ -0,0 +1,317 @@
+/**
+ * Launch dialog helpers: resolve cwd suggestions, scoped model choices, and thinking options.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** @typedef {"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max"} ThinkingLevel */
+
+/**
+ * @typedef {Object} LaunchModelLike
+ * @property {string} provider
+ * @property {string} id
+ * @property {string=} name
+ * @property {boolean=} reasoning
+ * @property {Partial<Record<ThinkingLevel, string|null>>=} thinkingLevelMap
+ */
+
+/**
+ * @typedef {Object} LaunchModelChoice
+ * @property {LaunchModelLike} model
+ * @property {ThinkingLevel=} thinkingLevel
+ */
+
+/**
+ * @typedef {Object} LaunchContext
+ * @property {LaunchModelChoice[]} choices
+ * @property {LaunchModelLike|null} selectedModel
+ * @property {ThinkingLevel} thinking
+ * @property {ThinkingLevel[]} thinkingOptions
+ * @property {"scoped"|"all"} scopeSource
+ */
+
+export const THINKING_LEVELS = /** @type {const} */ (["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+/** @param {unknown} value @returns {value is ThinkingLevel} */
+export function isThinkingLevel(value) {
+	return typeof value === "string" && THINKING_LEVELS.includes(/** @type {ThinkingLevel} */ (value));
+}
+
+/** @param {LaunchModelLike|null|undefined} model */
+export function canonicalModelRef(model) {
+	return model ? `${model.provider}/${model.id}` : "";
+}
+
+/** @param {LaunchModelLike|null|undefined} a @param {LaunchModelLike|null|undefined} b */
+export function sameModel(a, b) {
+	return Boolean(a && b && a.provider === b.provider && a.id === b.id);
+}
+
+/** @param {LaunchModelLike|null|undefined} model @returns {ThinkingLevel[]} */
+export function supportedThinkingLevels(model) {
+	if (!model?.reasoning) return ["off"];
+	const map = model.thinkingLevelMap ?? {};
+	const levels = THINKING_LEVELS.filter((level) => map[level] !== null);
+	return levels.length ? levels : [...THINKING_LEVELS];
+}
+
+/**
+ * @param {LaunchModelLike|null|undefined} model
+ * @param {ThinkingLevel|undefined|null} requested
+ * @param {ThinkingLevel=} fallback
+ * @returns {ThinkingLevel}
+ */
+export function clampThinkingLevel(model, requested, fallback = "off") {
+	const supported = supportedThinkingLevels(model);
+	if (requested && supported.includes(requested)) return requested;
+	if (supported.includes(fallback)) return fallback;
+	return supported[0] ?? "off";
+}
+
+/**
+ * Resolve the model choices for a cwd using pi's scoped-model settings semantics.
+ * Falls back to all available models when no scoped models are configured or none resolve.
+ *
+ * @param {string} cwd
+ * @param {LaunchModelLike[]} availableModels
+ * @param {LaunchModelLike|null|undefined} preferredModel
+ * @param {ThinkingLevel|undefined|null} preferredThinking
+ * @returns {LaunchContext}
+ */
+export function resolveLaunchContext(cwd, availableModels, preferredModel, preferredThinking) {
+	const settings = SettingsManager.create(cwd);
+	const patterns = settings.getEnabledModels();
+	const scoped = resolveScopedModels(patterns, availableModels);
+	const fallbackChoices = sortModels(availableModels, preferredModel).map((model) => ({ model }));
+	const choices = scoped.length ? scoped : fallbackChoices;
+	const scopeSource = scoped.length ? "scoped" : "all";
+	const defaultThinking = normalizeThinking(settings.getDefaultThinkingLevel()) ?? preferredThinking ?? "off";
+	const selectedChoice = preferredModel ? choices.find((choice) => sameModel(choice.model, preferredModel)) : undefined;
+	const selectedModel = selectedChoice?.model ?? choices[0]?.model ?? preferredModel ?? null;
+	const thinkingBase = selectedChoice?.thinkingLevel ?? preferredThinking ?? defaultThinking;
+	const thinking = clampThinkingLevel(selectedModel, thinkingBase, defaultThinking);
+	return {
+		choices,
+		selectedModel,
+		thinking,
+		thinkingOptions: supportedThinkingLevels(selectedModel),
+		scopeSource,
+	};
+}
+
+/**
+ * @param {string|undefined} value
+ * @returns {ThinkingLevel|undefined}
+ */
+function normalizeThinking(value) {
+	return isThinkingLevel(value) ? value : undefined;
+}
+
+/** @param {LaunchModelLike[]} models @param {LaunchModelLike|null|undefined} current */
+function sortModels(models, current) {
+	return [...models].sort((a, b) => {
+		const aCurrent = sameModel(a, current);
+		const bCurrent = sameModel(b, current);
+		if (aCurrent && !bCurrent) return -1;
+		if (!aCurrent && bCurrent) return 1;
+		const providerCmp = a.provider.localeCompare(b.provider);
+		return providerCmp !== 0 ? providerCmp : a.id.localeCompare(b.id);
+	});
+}
+
+/** @param {string|undefined} patterns @param {LaunchModelLike[]} _available */
+function resolveScopedModels(patterns, _available) {
+	const available = Array.isArray(_available) ? _available : [];
+	if (!patterns?.length) return [];
+	/** @type {LaunchModelChoice[]} */
+	const scoped = [];
+	for (const rawPattern of patterns) {
+		const pattern = String(rawPattern || "").trim();
+		if (!pattern) continue;
+		if (hasGlob(pattern)) {
+			const colonIdx = pattern.lastIndexOf(":");
+			let globPattern = pattern;
+			/** @type {ThinkingLevel|undefined} */
+			let thinkingLevel;
+			if (colonIdx !== -1) {
+				const suffix = pattern.slice(colonIdx + 1);
+				if (isThinkingLevel(suffix)) {
+					thinkingLevel = suffix;
+					globPattern = pattern.slice(0, colonIdx);
+				}
+			}
+			const matches = available.filter((model) => matchGlob(`${model.provider}/${model.id}`, globPattern) || matchGlob(model.id, globPattern));
+			for (const model of matches) pushUnique(scoped, { model, thinkingLevel });
+			continue;
+		}
+		const parsed = parseModelPattern(pattern, available);
+		if (parsed.model) pushUnique(scoped, { model: parsed.model, thinkingLevel: parsed.thinkingLevel });
+	}
+	return scoped;
+}
+
+/** @param {LaunchModelChoice[]} choices @param {LaunchModelChoice} choice */
+function pushUnique(choices, choice) {
+	if (!choices.find((entry) => sameModel(entry.model, choice.model))) choices.push(choice);
+}
+
+/** @param {string} pattern */
+function hasGlob(pattern) {
+	return /[*?[]/.test(pattern);
+}
+
+/** @param {string} text @param {string} glob */
+function matchGlob(text, glob) {
+	try {
+		return new RegExp(`^${globToRegExp(glob)}$`, "i").test(text);
+	} catch {
+		return false;
+	}
+}
+
+/** @param {string} glob */
+function globToRegExp(glob) {
+	let out = "";
+	for (let i = 0; i < glob.length; i++) {
+		const ch = glob[i];
+		if (ch === "*") {
+			out += ".*";
+			continue;
+		}
+		if (ch === "?") {
+			out += ".";
+			continue;
+		}
+		if (ch === "[") {
+			const end = glob.indexOf("]", i + 1);
+			if (end > i) {
+				out += glob.slice(i, end + 1);
+				i = end;
+				continue;
+			}
+		}
+		out += escapeRegExp(ch);
+	}
+	return out;
+}
+
+/** @param {string} text */
+function escapeRegExp(text) {
+	return text.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&");
+}
+
+/** @param {string} id */
+function isAlias(id) {
+	if (id.endsWith("-latest")) return true;
+	return !/-\d{8}$/.test(id);
+}
+
+/** @param {string} modelReference @param {LaunchModelLike[]} availableModels */
+function findExactModelReferenceMatch(modelReference, availableModels) {
+	const trimmed = modelReference.trim();
+	if (!trimmed) return undefined;
+	const lower = trimmed.toLowerCase();
+	const canonicalMatches = availableModels.filter((model) => `${model.provider}/${model.id}`.toLowerCase() === lower);
+	if (canonicalMatches.length === 1) return canonicalMatches[0];
+	if (canonicalMatches.length > 1) return undefined;
+	const slashIndex = trimmed.indexOf("/");
+	if (slashIndex !== -1) {
+		const provider = trimmed.slice(0, slashIndex).trim();
+		const modelId = trimmed.slice(slashIndex + 1).trim();
+		if (provider && modelId) {
+			const providerMatches = availableModels.filter((model) => model.provider.toLowerCase() === provider.toLowerCase() && model.id.toLowerCase() === modelId.toLowerCase());
+			if (providerMatches.length === 1) return providerMatches[0];
+			if (providerMatches.length > 1) return undefined;
+		}
+	}
+	const idMatches = availableModels.filter((model) => model.id.toLowerCase() === lower);
+	return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+
+/** @param {string} modelPattern @param {LaunchModelLike[]} availableModels */
+function tryMatchModel(modelPattern, availableModels) {
+	const exact = findExactModelReferenceMatch(modelPattern, availableModels);
+	if (exact) return exact;
+	const lower = modelPattern.toLowerCase();
+	const matches = availableModels.filter((model) => model.id.toLowerCase().includes(lower) || model.name?.toLowerCase().includes(lower));
+	if (!matches.length) return undefined;
+	const aliases = matches.filter((model) => isAlias(model.id));
+	const dated = matches.filter((model) => !isAlias(model.id));
+	if (aliases.length) return aliases.sort((a, b) => b.id.localeCompare(a.id))[0];
+	return dated.sort((a, b) => b.id.localeCompare(a.id))[0];
+}
+
+/** @param {string} pattern @param {LaunchModelLike[]} availableModels */
+function parseModelPattern(pattern, availableModels) {
+	const exact = tryMatchModel(pattern, availableModels);
+	if (exact) return { model: exact, thinkingLevel: undefined };
+	const lastColon = pattern.lastIndexOf(":");
+	if (lastColon === -1) return { model: undefined, thinkingLevel: undefined };
+	const prefix = pattern.slice(0, lastColon);
+	const suffix = pattern.slice(lastColon + 1);
+	if (isThinkingLevel(suffix)) {
+		const result = parseModelPattern(prefix, availableModels);
+		if (result.model) return { model: result.model, thinkingLevel: suffix };
+		return result;
+	}
+	return parseModelPattern(prefix, availableModels);
+}
+
+/** @param {string} input */
+function expandHome(input) {
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (!home) return input;
+	if (input === "~") return home;
+	if (input.startsWith(`~${path.sep}`)) return path.join(home, input.slice(2));
+	return input;
+}
+
+/** @param {string} value @param {string} baseCwd */
+export function resolveDirectoryValue(value, baseCwd) {
+	const raw = String(value || "").trim();
+	if (!raw) return existsDir(baseCwd) ? path.resolve(baseCwd) : null;
+	const expanded = expandHome(raw);
+	const resolved = path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(baseCwd, expanded);
+	return existsDir(resolved) ? resolved : null;
+}
+
+/**
+ * @param {string} query
+ * @param {string} baseCwd
+ * @param {number=} limit
+ * @returns {string[]}
+ */
+export function listDirectorySuggestions(query, baseCwd, limit = 8) {
+	const raw = String(query || "").trim();
+	const expanded = expandHome(raw);
+	const resolved = raw ? (path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(baseCwd, expanded)) : path.resolve(baseCwd);
+	let searchDir = resolved;
+	let fragment = "";
+	if (!existsDir(resolved) || !raw.endsWith(path.sep)) {
+		searchDir = existsDir(resolved) ? resolved : path.dirname(resolved);
+		fragment = existsDir(resolved) ? "" : path.basename(resolved);
+	}
+	/** @type {string[]} */
+	const out = [];
+	if (existsDir(resolved)) out.push(path.resolve(resolved));
+	if (existsDir(searchDir)) {
+		const lowerFragment = fragment.toLowerCase();
+		const children = readdirSync(searchDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.filter((name) => !lowerFragment || name.toLowerCase().includes(lowerFragment))
+			.sort((a, b) => a.localeCompare(b));
+		for (const name of children) out.push(path.join(searchDir, name));
+	}
+	return Array.from(new Set(out)).slice(0, Math.max(1, limit));
+}
+
+/** @param {string} dir */
+function existsDir(dir) {
+	try {
+		return existsSync(dir) && statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+}

package/src/core/launch.mjs

@@ -0,0 +1,116 @@
+/**
+ * Launch a detached job-runner process for one run.
+ *
+ * The runner is a plain `.mjs` spawned with `node`, fully detached (its own process
+ * group, stdio ignored) so it survives the parent Pi reloading or exiting. The parent
+ * records the runner pid in `pid.json` and watches the store files the runner writes.
+ */
+import { spawn } from "node:child_process";
+import { atomicWriteJson } from "./atomic.mjs";
+import { resolveNode } from "./invocation.mjs";
+import * as P from "./paths.mjs";
+import { writePid } from "./store.mjs";
+
+/** @typedef {import("./types.mjs").RunConfig} RunConfig */
+/** @typedef {import("./types.mjs").HostConfig} HostConfig */
+/** @typedef {import("./types.mjs").TitleConfig} TitleConfig */
+/** @typedef {import("./types.mjs").AutoStateConfig} AutoStateConfig */
+
+/**
+ * @param {string} root
+ * @param {RunConfig} config
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null, configPath: string }}
+ */
+export function launchRun(root, config, opts) {
+	const runDir = P.runDir(root, config.viewId, config.runId);
+	const configPath = `${runDir}/config.json`;
+	atomicWriteJson(configPath, config);
+
+	const node = opts.node ?? resolveNode();
+	const child = spawn(node, [opts.runnerScript, configPath], {
+		cwd: config.cwd,
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+	});
+	child.unref();
+
+	const pid = child.pid ?? null;
+	// Record the *runner/monitor* pid for liveness polling (the worker pid is tracked
+	// inside status.json by the runner itself).
+	writePid(root, config.viewId, config.runId, pid);
+	return { pid, configPath };
+}
+
+/**
+ * Launch a detached PTY host for a view. The host owns a long-lived child Pi and
+ * exposes a JSONL control socket for attach/input/resize/terminate.
+ * @param {string} root
+ * @param {HostConfig} config
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null, configPath: string }}
+ */
+export function launchHost(root, config, opts) {
+	const configPath = P.hostConfigPath(root, config.viewId);
+	atomicWriteJson(configPath, config);
+
+	const node = opts.node ?? resolveNode();
+	const child = spawn(node, [opts.runnerScript, configPath], {
+		cwd: config.cwd,
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+	});
+	child.unref();
+
+	return { pid: child.pid ?? null, configPath };
+}
+
+/**
+ * Launch a detached title runner for a view. Best-effort only: it may update `meta.json`
+ * later with a short GPT-generated name derived from the initial task prompt.
+ * @param {string} root
+ * @param {TitleConfig} config
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null, configPath: string }}
+ */
+export function launchTitle(root, config, opts) {
+	const configPath = P.titleConfigPath(root, config.viewId);
+	atomicWriteJson(configPath, config);
+
+	const node = opts.node ?? resolveNode();
+	const child = spawn(node, [opts.runnerScript, configPath], {
+		cwd: config.cwd,
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+	});
+	child.unref();
+
+	return { pid: child.pid ?? null, configPath };
+}
+
+/**
+ * Launch a detached auto-state classifier for a view. Best-effort: it may update
+ * state.json later with a model-refined terminal bucket.
+ * @param {string} root
+ * @param {AutoStateConfig} config
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null, configPath: string }}
+ */
+export function launchAutoState(root, config, opts) {
+	const configPath = P.autoStateConfigPath(root, config.viewId);
+	atomicWriteJson(configPath, config);
+
+	const node = opts.node ?? resolveNode();
+	const child = spawn(node, [opts.runnerScript, configPath], {
+		cwd: config.cwd,
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+	});
+	child.unref();
+
+	return { pid: child.pid ?? null, configPath };
+}

package/src/core/locks.mjs

@@ -0,0 +1,80 @@
+/**
+ * Tiny dependency-free synchronous file lock helpers for local agent-board artifacts.
+ * Locks use atomic mkdir on a sibling .lock directory and are cleaned up in finally.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { ensureDir } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+
+const DEFAULT_STALE_MS = 30_000;
+
+/**
+ * @template T
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @param {{ staleMs?: number }} [opts]
+ * @returns {T}
+ */
+export function withFileLockSync(lockPath, fn, opts = {}) {
+	const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+	acquireLock(lockPath, staleMs);
+	try {
+		return fn();
+	} finally {
+		releaseLock(lockPath);
+	}
+}
+
+/**
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} name
+ * @param {() => T} fn
+ * @param {{ staleMs?: number }} [opts]
+ * @returns {T}
+ */
+export function withViewLockSync(root, viewId, name, fn, opts = {}) {
+	return withFileLockSync(P.viewLockPath(root, viewId, name), fn, opts);
+}
+
+/** @param {string} lockPath @param {number} staleMs */
+function acquireLock(lockPath, staleMs) {
+	ensureDir(path.dirname(lockPath));
+	const started = Date.now();
+	while (true) {
+		try {
+			mkdirSync(lockPath);
+			writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }), "utf8");
+			return;
+		} catch (err) {
+			if (!isLockStale(lockPath, staleMs) && Date.now() - started < Math.max(250, staleMs)) {
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+				continue;
+			}
+			releaseLock(lockPath);
+		}
+	}
+}
+
+/** @param {string} lockPath @param {number} staleMs */
+function isLockStale(lockPath, staleMs) {
+	try {
+		if (!existsSync(lockPath)) return false;
+		const raw = readFileSync(path.join(lockPath, "owner.json"), "utf8");
+		const owner = JSON.parse(raw);
+		return Date.now() - Number(owner.at ?? 0) > staleMs;
+	} catch {
+		return true;
+	}
+}
+
+/** @param {string} lockPath */
+function releaseLock(lockPath) {
+	try {
+		rmSync(lockPath, { recursive: true, force: true });
+	} catch {
+		/* best effort */
+	}
+}

package/src/core/paths.mjs

@@ -0,0 +1,86 @@
+/**
+ * Filesystem layout for the agent-board store.
+ *
+ * Every helper takes an explicit `root` so tests can point at a tmp dir.
+ * The live default is `~/.pi/agent/agent-board/` (override with $AGENT_BOARD_ROOT;
+ * legacy $AGENT_VIEW_ROOT is also honored for migration).
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** @returns {string} the live store root (env override or ~/.pi/agent/agent-board). */
+export function defaultRoot() {
+	if (process.env.AGENT_BOARD_ROOT) return path.resolve(process.env.AGENT_BOARD_ROOT);
+	if (process.env.AGENT_VIEW_ROOT) return path.resolve(process.env.AGENT_VIEW_ROOT);
+	return path.join(os.homedir(), ".pi", "agent", "agent-board");
+}
+
+/** @param {string} root */
+export const rosterPath = (root) => path.join(root, "roster.json");
+/** @param {string} root */
+export const launchPrefsPath = (root) => path.join(root, "launch-prefs.json");
+/** @param {string} root */
+export const gcHistoryPath = (root) => path.join(root, "gc-history.jsonl");
+
+/** @param {string} root */
+export const viewsDir = (root) => path.join(root, "views");
+/** @param {string} root @param {string} viewId */
+export const viewDir = (root, viewId) => path.join(root, "views", viewId);
+/** @param {string} root @param {string} viewId */
+export const metaPath = (root, viewId) => path.join(viewDir(root, viewId), "meta.json");
+/** @param {string} root @param {string} viewId */
+export const statePath = (root, viewId) => path.join(viewDir(root, viewId), "state.json");
+/** @param {string} root @param {string} viewId */
+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");
+/** @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 */
+export const autoStateConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "auto-state-config.json");
+/** @param {string} root @param {string} viewId */
+export const controlSocketPath = (root, viewId) => path.join(viewDir(root, viewId), "control.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 */
+export const hostPidPath = (root, viewId) => path.join(viewDir(root, viewId), "host-pid.json");
+/** @param {string} root @param {string} viewId */
+export const runsDir = (root, viewId) => path.join(viewDir(root, viewId), "runs");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const runDir = (root, viewId, runId) => path.join(runsDir(root, viewId), runId);
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const statusPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "status.json");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const eventsPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "events.jsonl");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const stdoutPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "stdout.log");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const stderrPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "stderr.log");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const pidPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "pid.json");
+/** @param {string} root @param {string} viewId */
+export const diagnosticsPath = (root, viewId) => path.join(viewDir(root, viewId), "diagnostics.jsonl");
+/** @param {string} root @param {string} viewId */
+export const evidencePath = (root, viewId) => path.join(viewDir(root, viewId), "evidence.json");
+/** @param {string} root @param {string} viewId */
+export const viewEvidencePath = evidencePath;
+/** @param {string} root @param {string} viewId */
+export const followUpQueuePath = (root, viewId) => path.join(viewDir(root, viewId), "queue.json");
+/** @param {string} root @param {string} viewId */
+export const queuePath = followUpQueuePath;
+/** @param {string} root @param {string} viewId */
+export const steeringPath = (root, viewId) => path.join(viewDir(root, viewId), "steering.json");
+/** @param {string} root @param {string} viewId @param {string} name */
+export const viewLockPath = (root, viewId, name) => path.join(viewDir(root, viewId), `${name}.lock`);
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const runEvidencePath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "evidence.json");
+
+/** @param {string} root */
+export const sessionsDir = (root) => path.join(root, "sessions");
+/** @param {string} root @param {string} viewId */
+export const sessionFilePath = (root, viewId) => path.join(sessionsDir(root), `${viewId}.jsonl`);
+
+/** @param {string} root */
+export const worktreesDir = (root) => path.join(root, "worktrees");
+/** @param {string} root @param {string} viewId */
+export const worktreePath = (root, viewId) => path.join(worktreesDir(root), viewId);

package/src/core/pid.mjs

@@ -0,0 +1,42 @@
+/** Process liveness checks. */
+
+/**
+ * Whether `pid` refers to a live process.
+ * `process.kill(pid, 0)` throws ESRCH when the process is gone, and EPERM when it
+ * exists but we lack permission to signal it — EPERM still means "alive".
+ * @param {number|null|undefined} pid
+ * @returns {boolean}
+ */
+export function isAlive(pid) {
+	if (!pid || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return /** @type {NodeJS.ErrnoException} */ (err).code === "EPERM";
+	}
+}
+
+/**
+ * Try to terminate a process tree gently, then force after `graceMs`.
+ * Safe no-op if already dead.
+ * @param {number|null|undefined} pid
+ * @param {number} [graceMs]
+ */
+export function killProcess(pid, graceMs = 4000) {
+	if (!isAlive(pid)) return;
+	try {
+		process.kill(/** @type {number} */ (pid), "SIGTERM");
+	} catch {
+		/* ignore */
+	}
+	setTimeout(() => {
+		if (isAlive(pid)) {
+			try {
+				process.kill(/** @type {number} */ (pid), "SIGKILL");
+			} catch {
+				/* ignore */
+			}
+		}
+	}, graceMs).unref?.();
+}

package/src/core/prewarm-schedule.mjs

@@ -0,0 +1,41 @@
+/**
+ * Single-flight debounce for dashboard prewarm.
+ *
+ * Arrow-key navigation must move the selection and repaint immediately; host
+ * prewarm (which may spawn a PTY host and re-scan rows) is deferred so bursts
+ * of keypresses trigger exactly one prewarm for the final resting selection.
+ */
+
+/**
+ * @param {() => void} prewarm Invoked (with errors swallowed) once scheduling
+ *   goes quiet for `delayMs`. Re-reads current state at fire time.
+ * @param {number} [delayMs=200]
+ * @returns {{ schedule: () => void, cancel: () => void }}
+ */
+export function createPrewarmScheduler(prewarm, delayMs = 200) {
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let timer = null;
+	const fire = () => {
+		timer = null;
+		try {
+			prewarm();
+		} catch {
+			/* prewarm is best-effort; never break navigation */
+		}
+	};
+	return {
+		schedule() {
+			if (timer !== null) clearTimeout(timer);
+			const pending = setTimeout(fire, delayMs);
+			// Never let a pending debounce hold the event loop open on exit.
+			if (typeof pending.unref === "function") pending.unref();
+			timer = pending;
+		},
+		cancel() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		},
+	};
+}