@zhuxixi/pi-agent-board 0.6.2 → 0.7.0

package/runner/pty-runner.mjs

@@ -22,7 +22,9 @@ 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 { readHost, readState, updateOwnedHost, writeHost, writeState } from "../src/core/store.mjs";
+import { readHost, readState, updateOwnedHost, writeHost } from "../src/core/store.mjs";
+import { sendStateCommand } from "../src/core/coordinator-client.mjs";
+import { markRowFailedDirect } from "./pty-runner-legacy.mjs";
 import { ensureNodePtySpawnHelperExecutable } from "../src/core/pty-support.mjs";
 
 const requireForPty = createRequire(import.meta.url);
@@ -240,8 +242,12 @@ function legacyMain(config) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		update({ state: "failed", endedAt: Date.now(), exitCode: 1, error: message });
-		markRowFailed(config.root, config.viewId, `PTY host failed: ${message}`);
-		process.exit(1);
+		// The command settles within the client's own timeout (never throws), so
+		// the exit stays bounded while the fenced write gets its chance. Return
+		// instead of falling through: child is null here and the rest of this
+		// function assumes a spawned child.
+		void markRowFailed(config.root, config.viewId, `PTY host failed: ${message}`).finally(() => process.exit(1));
+		return;
 	}
 	childPid = child.pid ?? null;
 	update({ childPid });
@@ -754,7 +760,7 @@ async function ownedMain(config) {
 	} 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 markRowFailed(config.root, config.viewId, `PTY host failed: ${message}`);
 		await finishHost("child_spawn_failed", 1);
 		return;
 	}
@@ -1018,34 +1024,66 @@ function captureStartToken(pid) {
 }
 
 
-function markRowFailed(root, viewId, message) {
-	const now = Date.now();
-	const state = readState(root, viewId) ?? {
-		version: 1,
+/**
+ * Finalize the view row as failed when the PTY host itself fails (child spawn
+ * failure). Routed through the View State Coordinator as a fenced
+ * `host_run_failed` command (issue #91, PR #1 residual risk #2): a manually
+ * completed row rejects with manual_fence and stays completed, and a row
+ * re-pointed to a newer run rejects with stale_run.
+ *
+ * The runId is sourced from the row's current state.json (null = the row had
+ * no run) so the coordinator's stale_run guard stays effective; the
+ * coordinator cannot enforce this from its side because it has no visibility
+ * into what the host knows.
+ *
+ * Never throws: every client outcome is handled so the crash path cannot hang.
+ *  - applied → done (journaled + materialized by the coordinator).
+ *  - coordinator_disabled → legacy direct write (documented escape hatch).
+ *  - decided rejections (manual_fence / stale_run / no_change) → info
+ *    diagnostic; the coordinator's verdict governs.
+ *  - everything else (timeout / connection reset / unavailable) → warn
+ *    diagnostic: the outcome is unknown or the row could not be marked — the
+ *    runner still shuts down.
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} message
+ */
+async function markRowFailed(root, viewId, message) {
+	const knownRunId = readState(root, viewId)?.currentRunId ?? null;
+	const result = await sendStateCommand(root, {
+		type: "state_command",
 		viewId,
-		currentRunId: null,
-		semanticState: "queued",
-		processState: "exited",
-		summary: "Queued",
-		lastActivityAt: now,
-		updatedAt: now,
-		needsInput: false,
-		hasError: false,
-		latestAssistantPreview: "",
-		latestTool: null,
-		question: null,
-		pendingQuestions: [],
-		error: null,
-	};
-	state.semanticState = "failed";
-	state.processState = "exited";
-	state.summary = message;
-	state.hasError = true;
-	state.needsInput = false;
-	state.error = message;
-	state.updatedAt = now;
-	state.lastActivityAt = now;
-	writeState(root, state);
+		runId: knownRunId,
+		source: "pty-runner",
+		kind: "host_run_failed",
+		payload: { error: message },
+	});
+	if (result.status === "applied") return;
+	if (result.reason === "coordinator_disabled") {
+		markRowFailedDirect(root, viewId, message);
+		return;
+	}
+	if (result.reason === "manual_fence" || result.reason === "stale_run" || result.reason === "no_change") {
+		try {
+			appendDiagnostic(root, viewId, {
+				source: "runner",
+				level: "info",
+				code: "host_run_failed_skipped",
+				message: `Host failure not applied to the row (${result.reason})`,
+				details: { reason: result.reason },
+			});
+		} catch { /* best effort */ }
+		return;
+	}
+	try {
+		appendDiagnostic(root, viewId, {
+			source: "runner",
+			level: "warn",
+			code: "host_run_failed_ambiguous",
+			message: `Host failure outcome unknown (${result.reason}); the row may not reflect the failed host`,
+			details: { reason: result.reason },
+		});
+	} catch { /* best effort */ }
 }
 
 function failEarly(message) {

package/runner/state-coordinator.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * Detached View State Coordinator (issue #91, spec D3) — the single logical
+ * writer of state.json/status.json for one board root.
+ *
+ * Usage: node state-coordinator.mjs <root>
+ *
+ * Design contract:
+ * - Exactly one instance per root: a token-fenced lease (acquireOwnedViewLock on
+ *   the pseudo-view "_coordinator") is grabbed before anything else; a second
+ *   instance exits 0 immediately ("busy" is an expected, idempotent outcome).
+ * - Every semantic mutation arrives as a `state_command` over the JSONL control
+ *   socket and is decided by the pure layer (state-commands.mjs). This process
+ *   owns ALL side effects: durable journal append (fsync BEFORE materialize, so
+ *   boot replay can repair the crash window), materialization under a per-view
+ *   file lock, checkpoint + journal GC, and socket lifecycle.
+ * - Transient kinds (TRANSIENT_KINDS, run_progress) bypass the durable
+ *   machinery: validate → decide → materialize → reply, with no journal
+ *   append, no dedupe, and no checkpoint trigger — a periodic snapshot whose
+ *   next beat supersedes it. They still bump materializedRevision.
+ * - Idempotency: a processed commandId returns its original result forever —
+ *   from the in-memory ring first (bounded, covers the post-GC window), then
+ *   from the journal (findProcessedCommand). Duplicates never re-append.
+ * - Revisions: one global monotonic materializedRevision counter, initialized at
+ *   boot to max(checkpoint, max journal revision, max revision across views'
+ *   state.json), incremented once per applied command, and stamped identically
+ *   on state.json and the command's run status.json (spec 根治条件 5 scope).
+ * - Boot replay re-materializes every applied journal record from its stored
+ *   patches; per-file guards stamp only files strictly behind the recorded
+ *   revision, so a half-materialized pair (state.json written, status.json not)
+ *   repairs just the lagging half without moving the other one backwards. The
+ *   decision-time status binding (statusRunId) is recorded in the journal, so
+ *   replay is deterministic — no re-decision, no re-binding.
+ * - Legacy adoption: a view without materializedRevision is stamped as part of
+ *   its first applied command's single materialization write (no extra write).
+ * - AGENT_BOARD_COORDINATOR=off makes the process exit 0 immediately (tests and
+ *   the client's degradation path).
+ */
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:net";
+import { readJson } from "../src/core/atomic.mjs";
+import {
+	appendCommand,
+	findProcessedCommand,
+	gcJournal,
+	readCheckpoint,
+	readJournal,
+	repairJournalTail,
+	writeCheckpoint,
+} from "../src/core/coordinator-journal.mjs";
+import { ownsEndpoint } from "../src/core/host-coordination.mjs";
+import { acquireOwnedViewLock, withViewLockSync } from "../src/core/locks.mjs";
+import * as P from "../src/core/paths.mjs";
+import { readState, readStatus, writeState, writeStatus } from "../src/core/store.mjs";
+import { TRANSIENT_KINDS, decideStateTransition, validateCommand } from "../src/core/state-commands.mjs";
+import { COORDINATOR_PROTOCOL_VERSION } from "../src/core/coordinator-protocol.mjs";
+
+/** In-memory processed-command ring size (FIFO). Beyond the journal, this covers
+ *  idempotency when the journal prefix has already been GC'd away. */
+const PROCESSED_RING_MAX = 1000;
+/** Journal growth (bytes) that triggers checkpoint + GC. Keeps boot replay bounded. */
+const CHECKPOINT_THRESHOLD_BYTES = 262_144;
+/** Lease heartbeat — matches pty-runner's host-start lease cadence. */
+const HEARTBEAT_MS = 1000;
+/** Lifecycle kinds whose legacy write sites stamped state.lastActivityAt on
+ *  every persist (service markQueued/archive/adopt, job-runner plan-ready,
+ *  reconcile terminal sites). The decision layer stays clock-free, so the
+ *  shell adds the wall-clock stamp — into the patch BEFORE the journal
+ *  append, so boot replay re-applies the exact same fields deterministically
+ *  (there is no clock at replay time either). (Task 1 review F5.) */
+const LAST_ACTIVITY_STAMP_KINDS = new Set(["mark_queued", "archive_view", "adopt_session", "reconcile_finalize", "plan_ready", "mark_completed", "host_run_failed"]);
+/** Kinds whose status patch may CREATE the run's status file: they carry the
+ *  full status content for a run that has no materialized status yet. Every
+ *  other kind keeps PR #1's "patch presence ≠ file requirement" semantics
+ *  (e.g. mark_completed's `status: {autoState: null}` on a legacy row without
+ *  a status file must not fabricate one). */
+const STATUS_BOOTSTRAP_KINDS = new Set(["run_started", "followup_started"]);
+
+const root = process.argv[2];
+if (!root) {
+	process.stderr.write("state-coordinator: missing root argument\n");
+	process.exit(2);
+}
+if (process.env.AGENT_BOARD_COORDINATOR === "off") process.exit(0);
+
+main().catch((err) => {
+	process.stderr.write(`state-coordinator: fatal ${err?.stack || err}\n`);
+	process.exit(1);
+});
+
+async function main() {
+	const instanceId = randomBytes(8).toString("hex");
+	const startedAt = Date.now();
+
+	// 1. Lease first: a second coordinator is an expected, idempotent no-op.
+	// Identity carries a POSIX startToken (pty-runner pattern) so a SIGKILLed
+	// coordinator's lease can be reclaimed by the next instance after pid reuse.
+	/** @type {import("../src/core/locks.mjs").Lease} */
+	let lease;
+	try {
+		lease = acquireOwnedViewLock(root, "_coordinator", "state-coordinator", {
+			waitMs: 500,
+			identity: { pid: process.pid, startToken: captureStartToken(process.pid) },
+		});
+	} catch (err) {
+		process.stderr.write(`state-coordinator: lease unavailable (${err?.code ?? err?.message ?? "unknown"}); another instance may own it; exiting\n`);
+		process.exit(0);
+	}
+	const startTouchTimer = setInterval(() => {
+		try { lease?.touch(); } catch { /* best effort */ }
+	}, HEARTBEAT_MS);
+	startTouchTimer.unref?.();
+
+	// 2. Boot state: journal summary, processed-command ring, replay, counter init.
+	// Repair a crash-torn tail FIRST: without it the first post-restart append
+	// concatenates onto the torn line and that fsynced record becomes invisible
+	// to every readJournal / replay / revision scan below.
+	repairJournalTail(root);
+	const checkpoint = readCheckpoint(root) ?? { materializedRevision: 0, journalBytes: 0 };
+	const journal = readJournal(root);
+	/** @type {Map<string, { result: { status: string, reason: string|null }, materializedRevision: number }>} */
+	const processedCommands = new Map();
+	for (const record of journal) {
+		const commandId = record?.command?.commandId;
+		if (commandId && !processedCommands.has(commandId)) {
+			processedCommands.set(commandId, {
+				result: record.result ?? { status: "rejected", reason: "unknown" },
+				materializedRevision: record.materializedRevision ?? 0,
+			});
+		}
+	}
+
+	// Replay in journal order: re-materialize every applied record from its stored
+	// patches; materialize's per-file guards write only files strictly behind the
+	// recorded revision, so this repairs just the half that missed its write in a
+	// crash window and never moves the other half backwards.
+	for (const record of journal) {
+		if (record?.result?.status !== "applied") continue;
+		const viewId = record?.command?.viewId;
+		if (!viewId) continue;
+		materialize(viewId, record.command ?? {}, record.mutate ?? {}, record.materializedRevision ?? 0, record.statusRunId ?? null);
+	}
+
+	// Global revision counter: never reissue a revision that exists anywhere.
+	let revisionCounter = Math.max(checkpoint.materializedRevision ?? 0, 0);
+	for (const record of journal) revisionCounter = Math.max(revisionCounter, record.materializedRevision ?? 0);
+	if (existsSync(P.viewsDir(root))) {
+		for (const entry of readdirSync(P.viewsDir(root))) {
+			const state = readJson(P.statePath(root, entry), null);
+			revisionCounter = Math.max(revisionCounter, state?.materializedRevision ?? 0);
+		}
+	}
+	let lastCheckpointBytes = 0;
+
+	// 3. Control socket (JSONL, pty-runner's line-buffered server shape).
+	const socketPath = P.coordinatorEndpointPathFor(process.platform, root);
+	if (process.platform !== "win32" && existsSync(socketPath)) {
+		// Lease is ours: any leftover socket file belongs to a dead coordinator.
+		try { unlinkSync(socketPath); } catch { /* best effort */ }
+	}
+	/** {dev,ino} recorded at bind time; cleanup unlinks only this exact inode. */
+	let boundSocketIdentity = null;
+
+	const server = createServer((socket) => {
+		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("error", () => {}); // client vanished mid-request; nothing to answer
+	});
+
+	server.on("error", (err) => {
+		process.stderr.write(`state-coordinator: server error ${err instanceof Error ? err.message : String(err)}\n`);
+		shutdown(1);
+	});
+
+	server.listen(socketPath, () => {
+		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 */ }
+		}
+	});
+
+	let shuttingDown = false;
+	process.on("SIGTERM", () => shutdown(0));
+	process.on("SIGINT", () => shutdown(0));
+
+	function shutdown(code) {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		try { clearInterval(startTouchTimer); } catch { /* best effort */ }
+		try { server.close(); } catch { /* already closed */ }
+		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 */ }
+		}
+		try { lease.release(); } catch { /* best effort */ }
+		process.exit(code);
+	}
+
+	function send(socket, msg) {
+		socket.write(JSON.stringify(msg) + "\n");
+	}
+
+	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 "ping":
+				send(socket, { type: "pong", instanceId, startedAt, protocolVersion: COORDINATOR_PROTOCOL_VERSION });
+				break;
+			case "state_command":
+				send(socket, { type: "state_command_result", ...processStateCommand(msg) });
+				break;
+			default:
+				send(socket, { type: "error", message: "unknown type" });
+		}
+	}
+
+	/**
+	 * The command loop: validate → dedupe → decide → journal (fsync) → materialize
+	 * → remember → reply. Rejections are journaled too, so their exact reason is
+	 * replayable; duplicates short-circuit before any append.
+	 * @param {object} msg
+	 * @returns {{ commandId: string|null, status: string, reason: string|null, materializedRevision: number }}
+	 */
+	function processStateCommand(msg) {
+		const checked = validateCommand(msg);
+		if (!checked.ok) {
+			return {
+				commandId: typeof msg?.commandId === "string" ? msg.commandId : null,
+				status: "rejected",
+				reason: checked.error,
+				materializedRevision: 0,
+			};
+		}
+		const command = checked.command;
+		const transient = TRANSIENT_KINDS.includes(command.kind);
+
+		if (!transient) {
+			const known = lookupProcessed(command.commandId);
+			if (known) {
+				return { commandId: command.commandId, status: known.result.status, reason: known.result.reason, materializedRevision: known.materializedRevision };
+			}
+		}
+
+		const state = readState(root, command.viewId);
+		// Status consistency only binds the view's current run (spec 根治条件 5):
+		// no currentRunId → status.json plays no role in this command.
+		// Exception (Task 1 review F1): followup_started re-points the row at a
+		// NEW run carried in payload.newRunId (command.runId is deliberately null
+		// so the stale-run guard cannot fire against the finished parent run).
+		// Resolving the status from the parent here would overwrite the parent's
+		// status.json with the new run's bootstrap patch; resolving from newRunId
+		// finds no file and cleanly bootstraps the new run's status instead.
+		const statusRunId = command.kind === "followup_started"
+			? (typeof command.payload?.newRunId === "string" ? command.payload.newRunId : null)
+			: (command.runId ?? state?.currentRunId ?? null);
+		const status = statusRunId ? readStatus(root, command.viewId, statusRunId) : null;
+		const now = Date.now();
+		const decision = stampLegacyTimestamps(command, decideStateTransition(command, state, status, now), now);
+		const currentRevision = state?.materializedRevision ?? 0;
+
+		if (decision.action === "reject") {
+			if (transient) {
+				// Transient rejections are not replayable either — nothing was
+				// mutated, and journaling them would grow the journal for noise.
+				return { commandId: command.commandId ?? null, status: "rejected", reason: decision.reason, materializedRevision: currentRevision };
+			}
+			const result = { status: "rejected", reason: decision.reason };
+			const record = { command, result, materializedRevision: currentRevision, at: now };
+			const journalBytes = appendCommand(root, record);
+			rememberProcessed(command.commandId, result, currentRevision);
+			maybeCheckpoint(journalBytes);
+			return { commandId: command.commandId, status: "rejected", reason: decision.reason, materializedRevision: currentRevision };
+		}
+
+		const newRevision = revisionCounter + 1;
+		const result = { status: "applied", reason: decision.reason };
+		if (transient) {
+			// No journal, no processed ring, no checkpoint: a periodic snapshot —
+			// the next beat supersedes it.
+			materialize(command.viewId, command, decision.mutate, newRevision, statusRunId);
+			revisionCounter = newRevision;
+			return { commandId: command.commandId ?? null, status: "applied", reason: decision.reason, materializedRevision: newRevision };
+		}
+		// Journal first (fsync inside), materialize second: boot replay repairs
+		// the window between the two using the stored patches.
+		const record = { command, result, materializedRevision: newRevision, at: now, mutate: decision.mutate, statusRunId };
+		const journalBytes = appendCommand(root, record);
+		materialize(command.viewId, command, decision.mutate, newRevision, statusRunId);
+		revisionCounter = newRevision;
+		rememberProcessed(command.commandId, result, newRevision);
+		maybeCheckpoint(journalBytes);
+		return { commandId: command.commandId, status: "applied", reason: decision.reason, materializedRevision: newRevision };
+	}
+
+	/**
+	 * Merge patches onto state.json (and the run's status.json when it exists)
+	 * under the view's materialize lock, stamping the shared revision. Per-file
+	 * guards stamp only files strictly behind the record revision: the live path
+	 * always qualifies (the global counter is monotonic), while replay repairs
+	 * just the half that missed its write in a crash window and never moves the
+	 * other half backwards. A status patch without a status file is skipped —
+	 * patch presence ≠ file requirement (mark_completed always emits
+	 * `status: {autoState: null}`). The status run binding is the decision-time
+	 * one (`statusRunId`, recorded in the journal) so replay cannot re-bind a
+	 * runId-less patch to whatever run is current on disk at replay time;
+	 * `state.currentRunId` remains only as a legacy fallback for records written
+	 * before statusRunId existed.
+	 */
+	function materialize(viewId, command, mutate, revision, statusRunId) {
+		withViewLockSync(root, viewId, "state-materialize", () => {
+			const state = readState(root, viewId);
+			if (mutate?.state && state && (state.materializedRevision ?? 0) < revision) {
+				writeState(root, { ...state, ...mutate.state, materializedRevision: revision });
+			}
+			const runId = command?.runId ?? statusRunId ?? state?.currentRunId ?? null;
+			if (mutate?.status && runId) {
+				const status = readStatus(root, viewId, runId);
+				if (!status && STATUS_BOOTSTRAP_KINDS.has(command?.kind)) {
+					// run_started / followup_started carry the full status content for a
+					// run that has no status file yet — create it (F1's clean-bootstrap
+					// half). Identity fields come from the command context; the patch
+					// carries everything meaningful.
+					writeStatus(root, { version: 1, runId, viewId, ...mutate.status, materializedRevision: revision });
+				} else if (status && (status.materializedRevision ?? 0) < revision) {
+					writeStatus(root, { ...status, ...mutate.status, materializedRevision: revision });
+				}
+			}
+		});
+	}
+
+	/** Add the legacy wall-clock stamp to a decided patch (F5): see
+	 *  LAST_ACTIVITY_STAMP_KINDS. Applied before the journal append so the
+	 *  stored patches are exactly what replay re-materializes. */
+	function stampLegacyTimestamps(command, decision, now) {
+		if (decision.action !== "apply" || !LAST_ACTIVITY_STAMP_KINDS.has(command.kind)) return decision;
+		return { ...decision, mutate: { ...decision.mutate, state: { ...(decision.mutate.state ?? {}), lastActivityAt: now } } };
+	}
+
+	/** Memory ring first (covers the post-GC window), journal second. */
+	function lookupProcessed(commandId) {
+		const inMemory = processedCommands.get(commandId);
+		if (inMemory) return inMemory;
+		const result = findProcessedCommand(root, commandId);
+		if (!result) return null;
+		const entry = { result, materializedRevision: revisionOf(commandId) };
+		rememberProcessed(commandId, result, entry.materializedRevision);
+		return entry;
+	}
+
+	/** Revision recorded for a known commandId (journal scan; 0 if unrecorded). */
+	function revisionOf(commandId) {
+		for (const record of readJournal(root)) {
+			if (record?.command?.commandId === commandId) return record.materializedRevision ?? 0;
+		}
+		return 0;
+	}
+
+	function rememberProcessed(commandId, result, materializedRevision) {
+		processedCommands.set(commandId, { result, materializedRevision });
+		while (processedCommands.size > PROCESSED_RING_MAX) {
+			processedCommands.delete(processedCommands.keys().next().value);
+		}
+	}
+
+	/** Checkpoint + GC once the journal outgrows the threshold. GC only runs when
+	 *  the checkpoint write provably succeeded (journal module enforces this). */
+	function maybeCheckpoint(journalBytes) {
+		if (journalBytes - lastCheckpointBytes < CHECKPOINT_THRESHOLD_BYTES) return;
+		if (!writeCheckpoint(root, { materializedRevision: revisionCounter, journalBytes })) return;
+		lastCheckpointBytes = gcJournal(root);
+	}
+}
+
+/** POSIX process start token — /proc/<pid>/stat field 22 (starttime), stable
+ *  across exec(2). Same recipe as pty-runner: lets locks.mjs reclaim this
+ *  coordinator's lease after a SIGKILL even if the pid was reused. null on
+ *  failure or non-Linux platforms (reclaim degrades to "blocked" there — same
+ *  platform parity as PTY hosts). */
+function captureStartToken(pid) {
+	if (process.platform !== "linux" || !pid) return null;
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trimStart();
+		const fields = afterComm.split(/\s+/);
+		return fields[19] ?? null;
+	} catch {
+		return null;
+	}
+}

package/runner/state-runner.mjs

@@ -9,10 +9,11 @@
 import { spawn } from "node:child_process";
 import { readJson } from "../src/core/atomic.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
-import { applyAutoStateToStatus, applyAutoStateToViewState, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState } from "../src/core/auto-state.mjs";
+import { applyAutoStateToStatus, applyAutoStateToViewState, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
 import { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from "../src/core/evidence.mjs";
 import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
 import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
+import { sendStateCommand } from "../src/core/coordinator-client.mjs";
 
 async function main() {
 	const configPath = process.argv[2];
@@ -26,6 +27,10 @@ async function main() {
 
 	const state = readState(config.root, config.viewId);
 	if (!state || state.processState === "alive" || state.semanticState === "failed" || state.semanticState === "stopped") process.exit(0);
+	// Cheap pre-check (optimization only): skip a pointless command when the
+	// manual verdict is already materialized. The coordinator's manual_fence
+	// stays the authoritative guard for races after this read.
+	if (isManualCompletion(state)) process.exit(0);
 
 	const evidence = readEvidence(config.root, config.viewId);
 	const latest = latestEvidenceText(evidence) || state.latestAssistantPreview || state.summary || "";
@@ -45,24 +50,93 @@ async function main() {
 		classification = autoStateFromModelOrHeuristic(out, latest, { lastAgentActivityAt: state.lastAgentActivityAt ?? null });
 	}
 
-	let changed = false;
-	if (config.runId) {
-		const status = readStatus(config.root, config.viewId, config.runId);
-		if (status) {
-			changed = applyAutoStateToStatus(status, classification, Date.now()) || changed;
-			status.evidenceSummary = summarizeEvidence(finalizeEvidence(evidence, status, Date.now()));
-			writeStatus(config.root, status);
+	// Issue #91 (A8 path 2): the classification lands through the View State
+	// Coordinator — the single writer of state.json/status.json. A manual
+	// completion is fenced by the coordinator (manual_fence), so this late pass
+	// can no longer clobber the user's verdict (#46 class). Ambiguous transport
+	// outcomes (timeout / connection_reset) NEVER fall back to a direct write:
+	// the command may already be journaled, and the coordinator's boot replay
+	// is the recovery path.
+	const result = await sendStateCommand(config.root, {
+		type: "state_command",
+		viewId: config.viewId,
+		runId: config.runId ?? null,
+		source: "state-runner",
+		kind: "auto_state_classified",
+		expectedRevision: null,
+		payload: { classification },
+	});
+
+	if (result.status === "applied") {
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
+	} else if (result.reason === "manual_fence" || result.reason === "no_change" || result.reason === "stale_run") {
+		// Designed fences — informational, not errors: the coordinator is the
+		// authority and a manual completion wins by design.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified_skipped", message: `Auto-state classification not applied (${result.reason})`, details: { reason: result.reason } });
+	} else if (result.reason !== "coordinator_disabled") {
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, level: "warn", code: "auto_state_command_ambiguous", message: `Auto-state classification outcome unknown (${result.reason}); if the command was journaled, coordinator replay will recover it; otherwise the next classification pass will converge the row`, details: { reason: result.reason } });
+	}
+
+	if (result.reason === "coordinator_disabled") {
+		// Legacy escape hatch (AGENT_BOARD_COORDINATOR=off): pre-coordinator
+		// direct-write behavior, unchanged.
+		let changed = false;
+		if (config.runId) {
+			const status = readStatus(config.root, config.viewId, config.runId);
+			if (status) {
+				changed = applyAutoStateToStatus(status, classification, Date.now()) || changed;
+				status.evidenceSummary = summarizeEvidence(finalizeEvidence(evidence, status, Date.now()));
+				writeStatus(config.root, status);
+			}
 		}
+		const latestState = readState(config.root, config.viewId) ?? state;
+		changed = applyAutoStateToViewState(latestState, classification, Date.now()) || changed;
+		finalizeEvidence(evidence, { semanticState: latestState.semanticState, usage: null }, Date.now());
+		latestState.review = summarizeEvidence(evidence);
+		writeEvidence(config.root, evidence);
+		updateCodeRefsFromEvidence(config.root, config.viewId, evidence, meta);
+		writeState(config.root, latestState);
+		if (changed) {
+			appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
+		}
+		process.exit(0);
 	}
-	const latestState = readState(config.root, config.viewId) ?? state;
-	changed = applyAutoStateToViewState(latestState, classification, Date.now()) || changed;
-	finalizeEvidence(evidence, { semanticState: latestState.semanticState, usage: null }, Date.now());
-	latestState.review = summarizeEvidence(evidence);
+
+	// Evidence pipeline (coordinator-independent) stays direct: finalize the
+	// evidence snapshot from a FRESH state read (reads are not writes — the
+	// coordinator owns state.json/status.json writes, not reads), then persist
+	// the evidence artifacts and code-refs.
+	const postState = readState(config.root, config.viewId);
+	finalizeEvidence(evidence, { semanticState: postState?.semanticState ?? state.semanticState, usage: null }, Date.now());
 	writeEvidence(config.root, evidence);
 	updateCodeRefsFromEvidence(config.root, config.viewId, evidence, meta);
-	writeState(config.root, latestState);
-	if (changed) {
-		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
+
+	// Issue #91 PR #2 (Task 4): the evidence mirrors move behind the coordinator
+	// too — one patch_fields command materializes review/evidenceSummary on both
+	// files under a shared materializedRevision (previously two separately
+	// fenced direct writes). The coordinator's generic manual_fence / stale_run
+	// guards are authoritative; ambiguous outcomes (timeout / connection_reset)
+	// NEVER fall back to a direct write — if the command was journaled, boot
+	// replay recovers it, and the next classification pass re-derives mirrors
+	// from the evidence files either way.
+	const mirrorSummary = summarizeEvidence(evidence);
+	const patch = await sendStateCommand(config.root, {
+		type: "state_command",
+		viewId: config.viewId,
+		runId: config.runId ?? null,
+		source: "state-runner",
+		kind: "patch_fields",
+		expectedRevision: null,
+		payload: { state: { review: mirrorSummary }, status: { evidenceSummary: mirrorSummary } },
+	});
+	if (patch.status === "applied") {
+		// Quiet success — mirrors materialized by the coordinator.
+	} else if (patch.reason === "manual_fence" || patch.reason === "stale_run" || patch.reason === "no_change") {
+		// Designed fences — informational: a manual verdict or a newer run owns
+		// the row, or the mirrors already match.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "evidence_mirror_patch_skipped", message: `Evidence mirror patch not applied (${patch.reason})`, details: { reason: patch.reason } });
+	} else {
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, level: "warn", code: "evidence_mirror_patch_ambiguous", message: `Evidence mirror patch outcome unknown (${patch.reason}); if the command was journaled, coordinator replay will recover it; the next classification pass re-derives the mirrors from the evidence files`, details: { reason: patch.reason } });
 	}
 }