@zhuxixi/pi-agent-board 0.6.2 → 0.7.0

package/src/commands/bg.ts

@@ -51,7 +51,8 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 		},
 	});
 	const model = modelRef(ctx.model as any);
-	const adopted = service.adoptSession({
+	// adoptSession is async (routes through the view-state coordinator, issue #91).
+	const adopted = await service.adoptSession({
 		sessionFile,
 		cwd: ctx.cwd,
 		model,

package/src/core/coordinator-client.mjs

@@ -0,0 +1,313 @@
+/**
+ * Client for the detached View State Coordinator (issue #91, spec D3).
+ *
+ * Every semantic-state writer (dashboard service, job-runner, state-runner,
+ * CLI) submits `{type:"state_command"}` envelopes through `sendStateCommand`
+ * instead of writing state.json/status.json directly. The client resolves the
+ * coordinator endpoint, ensures a coordinator is live (spawning one if needed
+ * — idempotent via the coordinator's own lease), and waits for the matching
+ * `state_command_result`.
+ *
+ * Ambiguity contract (binding, from the Task 4 review): the coordinator can
+ * crash mid-command (e.g. an fs error) WITHOUT replying. The client then sees
+ * a connection reset or a timeout. Both mean the command MAY already be
+ * journaled and will replay on coordinator restart, so these outcomes are
+ * AMBIGUOUS: they resolve `{status:"rejected", reason:"timeout"|
+ * "connection_reset", materializedRevision:0}` and the client NEVER retries
+ * with a fresh commandId. Retrying with the SAME commandId after reconnect is
+ * safe (the coordinator dedupes) but is the caller's decision — which is why
+ * the caller may pin `command.commandId`.
+ *
+ * `materializedRevision: 0` on client-side outcomes means "no revision was
+ * observed" — it is not a store revision. Real coordinator replies always
+ * carry the actual revision (≥ 1 after any applied command; decided
+ * rejections carry the current revision).
+ */
+import { createConnection } from "node:net";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { newRunId } from "./ids.mjs";
+import { launchCoordinator } from "./launch.mjs";
+import * as P from "./paths.mjs";
+import { COORDINATOR_PROTOCOL_VERSION } from "./coordinator-protocol.mjs";
+
+const COORDINATOR_SCRIPT = fileURLToPath(
+	new URL("../../runner/state-coordinator.mjs", import.meta.url),
+);
+
+const PROBE_TIMEOUT_MS = 1_000;
+const ENSURE_WINDOW_MS = 10_000;
+const ENSURE_POLL_MS = 100;
+const COMMAND_TIMEOUT_MS = 5_000;
+
+/** @typedef {{ status: "applied"|"rejected", reason: string|null, materializedRevision: number }} StateCommandResult */
+/** @typedef {{ ok: boolean, instanceId?: string, pid?: number|null, error?: "coordinator_disabled"|"coordinator_unavailable"|"coordinator_stale_protocol" }} EnsureResult */
+
+/**
+ * Whether the coordinator is switched off for this process (tests/legacy
+ * escape hatch). `AGENT_BOARD_COORDINATOR=off` makes every command resolve
+ * `coordinator_disabled` so callers fall back to the pre-coordinator path.
+ * @returns {boolean}
+ */
+export function coordinatorDisabled() {
+	return /^(0|false|off|no)$/i.test(String(process.env.AGENT_BOARD_COORDINATOR ?? "").trim());
+}
+
+/**
+ * One probe round-trip: connect, ping, wait for the pong. The coordinator
+ * binds its socket only after boot replay, so a pong proves full readiness.
+ * @param {string} socketPath
+ * @param {(path: string) => import("node:net").Socket} connect
+ * @param {number} timeoutMs
+ * @returns {Promise<{ instanceId: string, protocolVersion: number }|null>} null on timeout/error;
+ *   a pong without a numeric protocolVersion counts as version 1 (pre-#107 baseline)
+ */
+function probeOnce(socketPath, connect, timeoutMs) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let buffer = "";
+		/** @type {import("node:net").Socket|null} */
+		let socket = null;
+		const finish = (instanceId) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			try { socket?.destroy(); } catch { /* best effort */ }
+			resolve(instanceId);
+		};
+		const timer = setTimeout(() => finish(null), timeoutMs);
+		timer.unref?.();
+		try {
+			socket = connect(socketPath);
+		} catch {
+			finish(null);
+			return;
+		}
+		// Missing filesystem sockets surface as async errors, not throw-on-connect
+		// (and Windows pipes never exist as files — never gate on existsSync).
+		socket.on("error", () => finish(null));
+		socket.on("connect", () => {
+			try {
+				socket?.write(JSON.stringify({ type: "ping" }) + "\n");
+			} catch {
+				finish(null);
+			}
+		});
+		socket.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const line of lines) {
+				if (!line.trim()) continue;
+				try {
+					const msg = JSON.parse(line);
+					if (msg?.type === "pong" && typeof msg.instanceId === "string") {
+						finish({
+							instanceId: msg.instanceId,
+							protocolVersion: typeof msg.protocolVersion === "number" ? msg.protocolVersion : 1,
+						});
+						return;
+					}
+				} catch {
+					// malformed line — keep waiting for the pong
+				}
+			}
+		});
+	});
+}
+
+/**
+ * Read the coordinator lease's owner.json and return the owning pid. The
+ * lease is written by whichever process owns the "_coordinator" lock, so it
+ * identifies the live coordinator even when its pong predates the pid field.
+ * @param {string} root
+ * @returns {number|null}
+ */
+function readCoordinatorLeasePid(root) {
+	try {
+		const lockPath = P.viewLockPath(root, "_coordinator", "state-coordinator");
+		const owner = JSON.parse(readFileSync(`${lockPath}/owner.json`, "utf8"));
+		const pid = Number(owner?.identity?.pid ?? owner?.pid ?? 0);
+		return Number.isFinite(pid) && pid > 0 ? pid : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Grace window for a SIGTERMed stale coordinator to unlink its socket. */
+const REPLACE_TIMEOUT_MS = 3_000;
+const REPLACE_POLL_MS = 50;
+
+/**
+ * Terminate a stale-protocol coordinator (issue #108) and wait for its socket
+ * to disappear so a fresh instance can bind. SIGTERM triggers the
+ * coordinator's graceful shutdown (socket unlink + lease release); its crash
+ * safety (fsync-before-materialize journal + boot replay) makes the kill safe
+ * even mid-command — an in-flight reply is the documented ambiguous outcome.
+ * @param {string} root
+ * @param {string} socketPath
+ * @returns {Promise<boolean>} whether the socket is gone (replacement can proceed)
+ */
+async function replaceStaleCoordinator(root, socketPath) {
+	const pid = readCoordinatorLeasePid(root);
+	if (pid != null) {
+		try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+	}
+	const deadline = Date.now() + REPLACE_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		if (!existsSync(socketPath)) return true;
+		await new Promise((r) => setTimeout(r, REPLACE_POLL_MS));
+	}
+	return false;
+}
+
+/**
+ * Make sure a coordinator is live for this board root: probe the endpoint and,
+ * on failure, spawn one and poll until it answers (the lease guarantees a
+ * single owner even under concurrent spawns — the loser exits silently).
+ * Repeated/concurrent calls are safe and cheap once a coordinator is up.
+ *
+ * Protocol gate (issue #108): a live coordinator reporting a protocol version
+ * older than this client's build is TERMINATED and respawned — otherwise a
+ * detached old-build instance survives every extension update and rejects
+ * every new command kind (`unknown_kind`), silently stranding state writes.
+ * If the stale instance cannot be replaced (unkillable, socket stuck), report
+ * `coordinator_stale_protocol` instead of pretending it is healthy.
+ *
+ * @param {string} root
+ * @param {{ runnerScript?: string, node?: string, probeTimeoutMs?: number, ensureWindowMs?: number, pollMs?: number, connect?: (path: string) => import("node:net").Socket }} [opts]
+ * @returns {Promise<EnsureResult>}
+ */
+export async function ensureCoordinator(root, opts = {}) {
+	if (coordinatorDisabled()) return { ok: false, error: "coordinator_disabled" };
+	const connect = opts.connect ?? createConnection;
+	const probeTimeoutMs = opts.probeTimeoutMs ?? PROBE_TIMEOUT_MS;
+	const windowMs = opts.ensureWindowMs ?? ENSURE_WINDOW_MS;
+	const pollMs = opts.pollMs ?? ENSURE_POLL_MS;
+	const socketPath = P.coordinatorEndpointPathFor(process.platform, root);
+
+	const first = await probeOnce(socketPath, connect, probeTimeoutMs);
+	if (first) {
+		if (first.protocolVersion >= COORDINATOR_PROTOCOL_VERSION) return { ok: true, instanceId: first.instanceId };
+		if (!await replaceStaleCoordinator(root, socketPath)) {
+			return { ok: false, error: "coordinator_stale_protocol" };
+		}
+	}
+
+	const launched = launchCoordinator(root, { runnerScript: opts.runnerScript ?? COORDINATOR_SCRIPT, node: opts.node });
+	const deadline = Date.now() + windowMs;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, pollMs));
+		const probe = await probeOnce(socketPath, connect, probeTimeoutMs);
+		if (probe && probe.protocolVersion >= COORDINATOR_PROTOCOL_VERSION) {
+			return { ok: true, instanceId: probe.instanceId, pid: launched.pid };
+		}
+	}
+	return { ok: false, error: "coordinator_unavailable", pid: launched.pid };
+}
+
+/**
+ * Submit one state command to the coordinator and wait for its result.
+ * Never throws; every failure path resolves a rejected result (see the
+ * ambiguity contract in the module doc).
+ * @param {string} root
+ * @param {object} command Command fields (`kind`, `viewId`, `runId`, `source`,
+ *   `expectedRevision`, `payload`); an explicit `commandId` pins the identity
+ *   for safe same-id retries, otherwise one is generated via `newRunId()`.
+ * @param {{ timeoutMs?: number, runnerScript?: string, node?: string, socketPath?: string, connect?: (path: string) => import("node:net").Socket, ensure?: typeof ensureCoordinator }} [opts]
+ * @returns {Promise<StateCommandResult>}
+ */
+export async function sendStateCommand(root, command, opts = {}) {
+	if (coordinatorDisabled()) {
+		return { status: "rejected", reason: "coordinator_disabled", materializedRevision: 0 };
+	}
+	const ensure = opts.ensure ?? ensureCoordinator;
+	const ensured = await ensure(root, {
+		runnerScript: opts.runnerScript,
+		node: opts.node,
+		connect: opts.connect,
+	});
+	if (!ensured.ok) {
+		return { status: "rejected", reason: ensured.error ?? "coordinator_unavailable", materializedRevision: 0 };
+	}
+
+	const timeoutMs = opts.timeoutMs ?? COMMAND_TIMEOUT_MS;
+	const connect = opts.connect ?? createConnection;
+	const socketPath = opts.socketPath ?? P.coordinatorEndpointPathFor(process.platform, root);
+	const commandId = typeof command.commandId === "string" && command.commandId
+		? command.commandId
+		: newRunId();
+	const envelope = { ...command, type: "state_command", commandId };
+
+	return await new Promise((resolve) => {
+		let settled = false;
+		let wrote = false;
+		let buffer = "";
+		/** @type {import("node:net").Socket|null} */
+		let socket = null;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			try { socket?.destroy(); } catch { /* best effort */ }
+			resolve(result);
+		};
+		const timer = setTimeout(() => finish({ status: "rejected", reason: "timeout", materializedRevision: 0 }), timeoutMs);
+		timer.unref?.();
+		try {
+			socket = connect(socketPath);
+		} catch {
+			// synchronous connect failure — nothing was sent, so not ambiguous
+			finish({ status: "rejected", reason: "connection_failed", materializedRevision: 0 });
+			return;
+		}
+		socket.on("error", () => {
+			// A reset AFTER the envelope was written is ambiguous (the command may
+			// be journaled); a failure before that is a plain delivery failure.
+			finish(wrote
+				? { status: "rejected", reason: "connection_reset", materializedRevision: 0 }
+				: { status: "rejected", reason: "connection_failed", materializedRevision: 0 });
+		});
+		socket.on("close", () => {
+			finish(wrote
+				? { status: "rejected", reason: "connection_reset", materializedRevision: 0 }
+				: { status: "rejected", reason: "connection_failed", materializedRevision: 0 });
+		});
+		socket.on("connect", () => {
+			try {
+				socket?.write(JSON.stringify(envelope) + "\n");
+				wrote = true;
+			} catch {
+				finish({ status: "rejected", reason: "connection_failed", materializedRevision: 0 });
+			}
+		});
+		socket.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const line of lines) {
+				if (!line.trim()) continue;
+				let msg;
+				try {
+					msg = JSON.parse(line);
+				} catch {
+					continue; // malformed line — keep waiting for the result
+				}
+				if (msg?.type === "state_command_result" && msg.commandId === commandId) {
+					finish({
+						status: msg.status === "applied" ? "applied" : "rejected",
+						reason: typeof msg.reason === "string" ? msg.reason : null,
+						materializedRevision: typeof msg.materializedRevision === "number" ? msg.materializedRevision : 0,
+					});
+					return;
+				}
+				if (msg?.type === "error") {
+					// Protocol misuse on our side — a definitive, non-journaled rejection.
+					finish({ status: "rejected", reason: `coordinator_error:${msg.message ?? "unknown"}`, materializedRevision: 0 });
+					return;
+				}
+				// pong/other lines are ignored — keep waiting for the matching result.
+			}
+		});
+	});
+}

package/src/core/coordinator-journal.mjs

@@ -0,0 +1,282 @@
+/**
+ * Durable command journal for the View State Coordinator (issue #91, spec D3).
+ *
+ * Write order contract: the coordinator appends a command record here and
+ * fsyncs BEFORE materializing state.json/status.json, so a crash between the
+ * two can be repaired by replaying the journal on restart. The checkpoint
+ * records how much of the journal (`journalBytes`) is already reflected in
+ * materialized state; GC may only drop that prefix after the checkpoint write
+ * itself succeeded. Full-coverage GC truncates the journal to empty: the
+ * covered commands leave the journal, so post-GC idempotency dedupe is owned
+ * by the coordinator's in-memory ring of recent commandIds (older commandIds
+ * fall back to current-state re-decision, whose apply paths are idempotent).
+ * `screen.log`'s fs-injection and temp+rename patterns are
+ * reused so every fs call is injectable in tests.
+ */
+import {
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export const JOURNAL_FILE_NAME = "state-journal.jsonl";
+export const CHECKPOINT_FILE_NAME = "state-journal.checkpoint.json";
+
+export const defaultJournalFs = Object.freeze({
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+});
+
+/** @param {string} root @returns {string} */
+export function journalPath(root) {
+	return join(root, JOURNAL_FILE_NAME);
+}
+
+/** @param {string} root @returns {string} */
+export function checkpointPath(root) {
+	return join(root, CHECKPOINT_FILE_NAME);
+}
+
+/**
+ * Append one processed-command record and fsync it before returning.
+ * @param {string} root
+ * @param {{ command: object, result: { status: string, reason: string|null }, materializedRevision: number, at: number }} record
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the append (usable as the next
+ *   checkpoint's `journalBytes`).
+ */
+export function appendCommand(root, record, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	fs.mkdirSync(dirname(file), { recursive: true });
+	const payload = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+	let fd;
+	try {
+		fd = fs.openSync(file, "a");
+		let offset = 0;
+		while (offset < payload.length) offset += fs.writeSync(fd, payload, offset, payload.length - offset);
+		fs.fsyncSync(fd);
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+	}
+	return fileSize(file, 0, fs);
+}
+
+/**
+ * Read every parseable journal record. A corrupt line (crash mid-append) is
+ * skipped — same semantics as atomic.mjs readJsonl, but with injectable fs.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {Array<{ command: object, result: { status: string, reason: string|null }, materializedRevision: number, at: number }>}
+ */
+export function readJournal(root, fs = defaultJournalFs) {
+	const data = readAllBytes(journalPath(root), fs);
+	const entries = [];
+	for (const line of data.toString("utf8").split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			entries.push(JSON.parse(trimmed));
+		} catch {
+			/* skip corrupt line */
+		}
+	}
+	return entries;
+}
+
+/**
+ * Idempotency lookup: the recorded result of an already-processed commandId,
+ * or null. On the (never-intended) duplicate, the FIRST entry is the original.
+ * @param {string} root
+ * @param {string} commandId
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {{ status: string, reason: string|null } | null}
+ */
+export function findProcessedCommand(root, commandId, fs = defaultJournalFs) {
+	for (const entry of readJournal(root, fs)) {
+		if (entry?.command?.commandId === commandId) return entry.result ?? null;
+	}
+	return null;
+}
+
+/**
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {{ materializedRevision: number, journalBytes: number } | null}
+ */
+export function readCheckpoint(root, fs = defaultJournalFs) {
+	const file = checkpointPath(root);
+	if (!fs.existsSync(file)) return null;
+	let raw;
+	try {
+		raw = readAllBytes(file, fs).toString("utf8");
+	} catch {
+		return null;
+	}
+	if (!raw.trim()) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Atomically replace the checkpoint (temp file + fsync + rename, screen-log
+ * pattern). Callers may only run gcJournal after this returns true.
+ * @param {string} root
+ * @param {{ materializedRevision: number, journalBytes: number }} checkpoint
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {boolean} whether the checkpoint is durably on disk
+ */
+export function writeCheckpoint(root, checkpoint, fs = defaultJournalFs) {
+	const file = checkpointPath(root);
+	fs.mkdirSync(dirname(file), { recursive: true });
+	return replaceFile(file, Buffer.from(`${JSON.stringify(checkpoint, null, 2)}\n`, "utf8"), fs);
+}
+
+/**
+ * Drop the journal prefix already covered by a successful checkpoint. Without
+ * a checkpoint this is a no-op (nothing proves the prefix is materialized).
+ * A checkpoint covering the whole journal truncates the file to empty — every
+ * covered record is materialized, and keeping it would grow the journal (and
+ * every findProcessedCommand/boot-replay scan) without bound.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the call
+ */
+export function gcJournal(root, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	const size = fileSize(file, 0, fs);
+	if (size === 0) return 0;
+	const checkpoint = readCheckpoint(root, fs);
+	if (!checkpoint || typeof checkpoint.journalBytes !== "number") return size;
+	const journalBytes = Math.floor(checkpoint.journalBytes);
+	if (journalBytes <= 0) return size;
+	if (journalBytes >= size) {
+		// Full coverage: everything in the file is materialized per the
+		// checkpoint. Truncate to empty; dedupe for covered commandIds is the
+		// coordinator's in-memory ring's job now.
+		if (!replaceFile(file, Buffer.alloc(0), fs)) return fileSize(file, size, fs);
+		return 0;
+	}
+	// journalBytes < size means the file exists with an un-checkpointed tail.
+	const tail = readAllBytes(file, fs, journalBytes);
+	if (!replaceFile(file, tail, fs)) return fileSize(file, size, fs);
+	return fileSize(file, tail.length, fs);
+}
+
+/**
+ * Truncate a crash-torn journal tail so the next append stays parseable.
+ *
+ * `appendCommand` writes `JSON+\n` in a partial-write loop; a process killed
+ * mid-append leaves bytes without a trailing newline. Without repair, the next
+ * append concatenates onto that torn line and the merged line is unparseable — the
+ * freshly fsynced+acked record becomes invisible to every readJournal /
+ * boot-replay / revision scan. The repair is byte-exact and cheap: scan
+ * backwards for the last newline and drop everything after it (a journal with
+ * no newline at all is torn from byte 0 and truncates to empty). Complete but
+ * corrupt lines are kept — readJournal already skips them.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the call
+ */
+export function repairJournalTail(root, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	const size = fileSize(file, 0, fs);
+	if (size === 0) return 0;
+	const data = readAllBytes(file, fs);
+	const lastNewline = data.lastIndexOf("\n");
+	if (lastNewline === data.length - 1) return size;
+	const keep = lastNewline + 1;
+	if (!replaceFile(file, data.subarray(0, keep), fs)) return fileSize(file, size, fs);
+	return keep;
+}
+
+/**
+ * Read the file from `position` (default 0) to EOF via injectable readSync.
+ * @param {string} file
+ * @param {typeof defaultJournalFs} fs
+ * @param {number} [position]
+ * @returns {Buffer}
+ */
+function readAllBytes(file, fs, position = 0) {
+	if (!fs.existsSync(file)) return Buffer.alloc(0);
+	let fd;
+	try {
+		fd = fs.openSync(file, "r");
+		const size = Math.max(0, fs.fstatSync(fd).size - position);
+		if (size === 0) return Buffer.alloc(0);
+		const output = Buffer.allocUnsafe(size);
+		let offset = 0;
+		while (offset < size) {
+			const read = fs.readSync(fd, output, offset, size - offset, position + offset);
+			if (read === 0) break;
+			offset += read;
+		}
+		return offset === size ? output : output.subarray(0, offset);
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+	}
+}
+
+/**
+ * Temp file + fsync + rename replacement (screen-log replaceScreenLog pattern).
+ * @param {string} file
+ * @param {Buffer} data
+ * @param {typeof defaultJournalFs} fs
+ * @returns {boolean}
+ */
+function replaceFile(file, data, fs) {
+	const temp = `${file}.${process.pid}.${tempSequence++}.tmp`;
+	let fd;
+	try {
+		fs.mkdirSync(dirname(file), { recursive: true });
+		fd = fs.openSync(temp, "w");
+		let offset = 0;
+		while (offset < data.length) offset += fs.writeSync(fd, data, offset, data.length - offset, offset);
+		fs.fsyncSync(fd);
+		fs.closeSync(fd);
+		fd = undefined;
+		fs.renameSync(temp, file);
+		return true;
+	} catch {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+		try { fs.unlinkSync(temp); } catch { /* best effort */ }
+		return false;
+	}
+}
+
+/** @param {string} file @param {number} fallback @param {typeof defaultJournalFs} fs */
+function fileSize(file, fallback, fs) {
+	try {
+		return fs.statSync(file).size;
+	} catch {
+		return fallback;
+	}
+}
+
+let tempSequence = 0;

package/src/core/coordinator-protocol.mjs

@@ -0,0 +1,12 @@
+/**
+ * Protocol version of the View State Coordinator control socket (issue #108).
+ *
+ * Bumped whenever a coordinator release adds command kinds or changes the
+ * envelope contract. A client built against version N refuses to talk to a
+ * coordinator reporting < N — a pong WITHOUT the field counts as version 1
+ * (the pre-#107 baseline) — and replaces the stale instance with a fresh one
+ * (SIGTERM via the coordinator lease pid, then respawn) instead of feeding
+ * it commands it cannot understand (`sync_foreground rejected (unknown_kind)`
+ * used to strand every foreground state write on extension updates).
+ */
+export const COORDINATOR_PROTOCOL_VERSION = 2;

package/src/core/launch.mjs

@@ -120,3 +120,18 @@ export function launchAutoState(root, config, opts) {
 
 	return { pid: child.pid ?? null, configPath };
 }
+
+/**
+ * Launch the detached view-state coordinator for a board root (issue #91, spec
+ * D3). No config file: the coordinator takes the root as its only argument.
+ * Idempotent by lease — a second instance loses the coordinator lease and
+ * exits silently, so callers may spawn freely on probe failure.
+ * @param {string} root
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null }}
+ */
+export function launchCoordinator(root, opts) {
+	const node = opts.node ?? resolveNode();
+	const child = spawnDetached(node, [opts.runnerScript, root], root);
+	return { pid: child.pid ?? null };
+}

package/src/core/paths.mjs

@@ -89,6 +89,22 @@ export function hostEndpointPathFor(platform, root, viewId, instanceId) {
 }
 /** @param {string} root @param {string} viewId */
 export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId), "screen.log");
+/**
+ * Well-known endpoint for the board-root View State Coordinator (issue #91, spec D3).
+ * Exactly one coordinator may own a root (token-fenced lease), so one stable path
+ * suffices; a stale POSIX socket left by a crashed coordinator is unlinked by the
+ * new lease owner before bind. win32 pipe names embed a 16-hex hash of the root to
+ * stay under the 256-char limit and keep per-root isolation.
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ */
+export function coordinatorEndpointPathFor(platform, root) {
+	if (platform === "win32") {
+		const hash = createHash("sha256").update(String(root)).digest("hex").slice(0, 16);
+		return `\\\\.\\pipe\\agent-board-coordinator-${hash}`;
+	}
+	return path.join(root, "coordinator.sock");
+}
 /** @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 */