@zhuxixi/pi-agent-board 0.7.0 → 0.8.0

package/runner/state-coordinator.mjs

@@ -74,8 +74,16 @@ const LAST_ACTIVITY_STAMP_KINDS = new Set(["mark_queued", "archive_view", "adopt
  *  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"]);
+ *  a status file must not fabricate one).
+ *
+ *  `run_progress` joins them (issue #91 hard-down residual closure): its beat
+ *  patch IS the runner's full in-memory status, and when the coordinator was
+ *  down through the runner's boot window (mark_queued applied, run_started
+ *  lost) the first post-recovery beat is the only surviving source that can
+ *  recreate the file — without it beats and finalize reject stale_run forever
+ *  and the row can never converge. The decision layer gates this on a
+ *  qualified live-run beat (full-shaped patch, matching string runId). */
+const STATUS_BOOTSTRAP_KINDS = new Set(["run_started", "followup_started", "run_progress"]);
 
 const root = process.argv[2];
 if (!root) {
@@ -312,32 +320,50 @@ async function main() {
 	 * 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.
+	 * other half backwards.
+	 *
+	 * Pairing invariant (issue #91 final review): EVERY applied revision pairs
+	 * BOTH files. A state-only patch (e.g. patch_fields markVisited) restamps
+	 * the existing status file's revision with no content change, and a
+	 * status-only patch restamps the state file the same way — a healthy
+	 * coordinator can never produce the asymmetric pair the reader-side
+	 * revision check (reconcile) treats as a crash signature. Journaled
+	 * state-only records heal on replay through this shared path. Residual:
+	 * a torn TRANSIENT beat (crash between the two writes, never journaled)
+	 * stays half-paired — ms-window × adjacent-crash, documented in the spec.
+	 *
+	 * 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 });
+			if (state && (state.materializedRevision ?? 0) < revision) {
+				writeState(root, mutate?.state
+					? { ...state, ...mutate.state, materializedRevision: revision }
+					: { ...state, materializedRevision: revision });
 			}
 			const runId = command?.runId ?? statusRunId ?? state?.currentRunId ?? null;
-			if (mutate?.status && runId) {
-				const status = readStatus(root, viewId, runId);
+			if (!runId) return;
+			const status = readStatus(root, viewId, runId);
+			if (mutate?.status) {
 				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.
+					// run_started / followup_started / (bootstrapping) run_progress
+					// carry the full status content for a run that has no status
+					// file yet — create it. 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 });
 				}
+			} else if (status && (status.materializedRevision ?? 0) < revision) {
+				// State-only patch: restamp the existing status file's revision with
+				// no content change (pairing invariant above).
+				writeStatus(root, { ...status, materializedRevision: revision });
 			}
 		});
 	}

package/runner/state-runner.mjs

@@ -14,6 +14,7 @@ import { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from
 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";
+import { commandRejectDiagnostic } from "../src/core/state-commands.mjs";
 
 async function main() {
 	const configPath = process.argv[2];
@@ -69,12 +70,12 @@ async function main() {
 
 	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 } });
+		// Unified decided/ambiguous classification (CR r2 issue-3): decided
+		// rejects (manual_fence/stale_run/…) log as info *_skipped — the
+		// coordinator's verdict is authoritative; only genuinely ambiguous
+		// outcomes (timeout/connection_reset) keep the recovery-path warn.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, ...commandRejectDiagnostic("auto_state", "Auto-state classification", result.reason, "otherwise the next classification pass will converge the row"), details: { reason: result.reason } });
 	}
 
 	if (result.reason === "coordinator_disabled") {

package/scripts/run-perf-gate.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Authoritative entry for the A11 perf gate (issue #121).
+ *
+ * Loudly refuses under coverage instrumentation: c8 sets NODE_V8_COVERAGE
+ * for its whole process tree, and instrumented latency measurements are
+ * invalid (2.5–6× inflation). Silently skipping here would manufacture a
+ * fake-green gate, so refusal is a nonzero exit with an explicit message.
+ *
+ * This script is the side-effect layer only — no decision logic, no
+ * measurement. The pure gate decision lives in test-support/perf-gate.mjs
+ * and serves the test file; do not merge the layers (spec §3.2/§4).
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+if (process.env.NODE_V8_COVERAGE !== undefined) {
+	console.error(
+		"run-perf-gate: refusing to measure under coverage instrumentation " +
+			"(NODE_V8_COVERAGE is set). Perf assertions are only valid without c8; " +
+			"run `npm run test:perf` directly, outside any coverage wrapper.",
+	);
+	process.exit(1);
+}
+
+const perfTest = fileURLToPath(new URL("../test/terminal-model-perf.test.mjs", import.meta.url));
+// No --test-concurrency=1: the flag requires Node 21+ but package.json
+// declares engines >=20, and it is a no-op while the gate runs a single
+// file (spec D3, revised 2026-09-20). Re-add it when a second perf file
+// lands — parallel measurement across files must stay impossible.
+const child = spawn(
+	process.execPath,
+	["--test", perfTest],
+	{ stdio: "inherit", env: { ...process.env, AGENT_BOARD_PERF_GATE: "1" } },
+);
+child.on("error", (err) => {
+	console.error(`run-perf-gate: failed to spawn the perf suite: ${err.message}`);
+	process.exit(1);
+});
+child.on("exit", (code) => process.exit(code ?? 1));

package/src/commands/agent-board.ts

@@ -106,7 +106,7 @@ export async function openDashboard(
 					currentThinkingLevel: options.currentThinkingLevel ?? "off",
 				});
 				interval = setInterval(() => {
-					service.reconcile();
+					void service.reconcile().catch(() => {});
 					comp.refresh();
 					requestDashboardRender(tui);
 				}, POLL_MS);
@@ -146,8 +146,8 @@ export async function dashboardAttachLoop(
 	let again = true;
 	while (again) {
 		const currentId = currentViewId(ctx, service);
-		if (currentId) service.markVisited?.(currentId);
-		service.reconcile();
+		if (currentId) void service.markVisited?.(currentId)?.catch(() => {});
+		void service.reconcile().catch(() => {});
 		const result = await openDashboard(ctx, service, {
 			initialSelectedId: selectedId,
 			currentThinkingLevel: getThinkingLevel?.(),
@@ -185,9 +185,9 @@ async function attach(
 	// Single async resolver entry: real probe + bounded recovery decide readiness (issue #70).
 	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
 	if (plan.plan === "open-pty") {
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		return { action: result.action === "closed" ? "closed" : "detached" };
 	}
 	if (plan.plan === "session-switch") {
@@ -197,7 +197,7 @@ async function attach(
 			return { action: "none" };
 		}
 		const name = latest.meta.name;
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const switchingOverlay = await showSwitchingOverlay(ctx, name, "PTY unavailable");
 		const result = await ctx.switchSession(latest.meta.sessionFile, {
 			withSession: async (replaced) => {
@@ -296,8 +296,8 @@ function installBackToDashboard(ctx: ExtensionCommandContext, service: ReturnTyp
 			try {
 				let selectedId = currentViewId(ctx, service);
 				while (true) {
-					if (selectedId) service.markVisited?.(selectedId);
-					service.reconcile();
+					if (selectedId) void service.markVisited?.(selectedId)?.catch(() => {});
+					void service.reconcile().catch(() => {});
 					const result = await openDashboard(ctx, service, { initialSelectedId: selectedId });
 					if (result.action !== "attach") return;
 					selectedId = result.viewId;

package/src/commands/attach-flow.ts

@@ -132,9 +132,9 @@ export async function attach(
 
 	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
 	if (plan.plan === "open-pty") {
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		return { action: result.action === "closed" ? "closed" : "detached" };
 	}
 	if (plan.plan === "session-switch") {
@@ -144,7 +144,7 @@ export async function attach(
 			return { action: "none" };
 		}
 		const name = latest.meta.name;
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const switchingOverlay = await showSwitchingOverlay(ctx, name, "PTY unavailable");
 		const result = await ctx.switchSession(latest.meta.sessionFile, {
 			withSession: async (replaced) => {
@@ -212,8 +212,8 @@ export function installBackToDashboard(
 			try {
 				let selectedId = currentViewId(ctx, service);
 				while (true) {
-					if (selectedId) service.markVisited?.(selectedId);
-					service.reconcile();
+					if (selectedId) void service.markVisited?.(selectedId)?.catch(() => {});
+					void service.reconcile().catch(() => {});
 					const result = await openDashboard(ctx, service, { initialSelectedId: selectedId });
 					if (result.action !== "attach") return;
 					selectedId = result.viewId;