@zhuxixi/pi-agent-board 0.6.2 → 0.8.0

package/src/core/status-consistency.mjs

@@ -0,0 +1,98 @@
+/**
+ * Reader-side revision consistency for the (state.json, status.json) pair
+ * (issue #91, spec D3 — 根治条件 5 read side).
+ *
+ * The View State Coordinator materializes both artifacts under one shared
+ * `materializedRevision` inside a single view lock. Disagreeing stamps
+ * therefore mean a coordinator crashed between its paired writes; readers
+ * must not combine the mismatched halves into one decision — skip the
+ * combination and request coordinator repair (a fresh coordinator's boot
+ * replay re-materializes the half-written pair from the journal).
+ *
+ * Legacy rows (written before revisions existed, or never touched by a
+ * command) may lack the field on either side; per the spec's legacy-migration
+ * clause the check is skipped for them — a missing stamp is never a desync.
+ */
+import { readState as readStateImpl, readStatus as readStatusImpl } from "./store.mjs";
+
+/**
+ * Whether the (state, status) pair is revision-desynced and must not be
+ * combined into one decision.
+ * @param {{ materializedRevision?: number|null }|null|undefined} state ViewState as read from state.json.
+ * @param {{ materializedRevision?: number|null }|null|undefined} status RunStatus as read from status.json.
+ * @returns {boolean}
+ */
+export function statusRevisionDesynced(state, status) {
+	if (state?.materializedRevision == null || status?.materializedRevision == null) return false;
+	return state.materializedRevision !== status.materializedRevision;
+}
+
+/**
+ * Re-read BOTH halves of the pair fresh and re-check the desync verdict.
+ *
+ * TOCTOU guard for long-lived readers (reconcile iterates a listRows snapshot;
+ * earlier rows' awaited commands let the on-disk pair advance past it): a
+ * suspicion raised against the snapshot must be confirmed against fresh reads
+ * before acting on it. Under the coordinator's view-lock pairing invariant
+ * both files move together, so a fresh consistent pair clears the suspicion;
+ * the residual window between the two fresh reads is sub-ms.
+ *
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string|null} runId
+ * @param {{ readState?: typeof readStateImpl, readStatus?: typeof readStatusImpl }} [readers] injection for tests.
+ * @returns {{ state: object|null, status: object|null, desynced: boolean }}
+ */
+export function rereadPair(root, viewId, runId, readers = {}) {
+	const readState = readers.readState ?? readStateImpl;
+	const readStatus = readers.readStatus ?? readStatusImpl;
+	const state = readState(root, viewId);
+	const status = readStatus(root, viewId, runId);
+	return { state, status, desynced: statusRevisionDesynced(state, status) };
+}
+
+/**
+ * Per-view episode throttle for desync reporting (issue #111 CR r1).
+ *
+ * A desync is a persistent CONDITION, not a one-shot event: reconcile runs on
+ * every dashboard poll (~700ms), and for unrepairable pairs (a torn transient
+ * beat has no journal record; or the coordinator is off) the condition never
+ * clears. Logging unthrottled would grow diagnostics.jsonl without bound.
+ * The throttle logs each distinct (stateRev:statusRev) pair once per viewer;
+ * a changed pair (progression, or a fresh crash at new revisions) logs again,
+ * and a repaired pair simply stops firing — no reset bookkeeping needed.
+ *
+ * Kick-retry tracking (issue #111 CR r2): a failed repair kick must not
+ * consume the recovery path — an idle dashboard would otherwise never run
+ * boot replay for a repairable pair. `markKickFailed`/`shouldRetryKick`
+ * track that independently of the diagnostic episode, so retries stay
+ * unbounded while the kick keeps failing while diagnostics stay once per
+ * episode. A successful kick clears the flag (the coordinator is up: boot
+ * replay already repaired a repairable pair; an unrepairable-torn pair
+ * gains nothing from re-kicking).
+ *
+ * @returns {{ shouldLog(viewId: string, stateRevision: number|null, statusRevision: number|null): boolean, markKickFailed(viewId: string): void, shouldRetryKick(viewId: string): boolean, clearKickFailed(viewId: string): void }}
+ */
+export function createDesyncEpisodeThrottle() {
+	/** @type {Map<string, string>} */
+	const lastLogged = new Map();
+	/** @type {Set<string>} */
+	const kickFailed = new Set();
+	return {
+		shouldLog(viewId, stateRevision, statusRevision) {
+			const pair = `${stateRevision ?? "null"}:${statusRevision ?? "null"}`;
+			if (lastLogged.get(viewId) === pair) return false;
+			lastLogged.set(viewId, pair);
+			return true;
+		},
+		markKickFailed(viewId) {
+			kickFailed.add(viewId);
+		},
+		shouldRetryKick(viewId) {
+			return kickFailed.has(viewId);
+		},
+		clearKickFailed(viewId) {
+			kickFailed.delete(viewId);
+		},
+	};
+}

package/src/core/store.mjs

@@ -8,9 +8,9 @@ import { atomicWriteJson, ensureDir, readJson } from "./atomic.mjs";
 import { sameHostOwner } from "./host-coordination.mjs";
 import { tryAcquireOwnedViewLock } from "./locks.mjs";
 import * as P from "./paths.mjs";
-import { isAlive } from "./pid.mjs";
+import { currentProcessIdentity, isAlive } from "./pid.mjs";
 import { readCodeRefs, summarizeCodeRefs } from "./code-refs-store.mjs";
-import { readDiagnosticSummary } from "./diagnostics.mjs";
+import { appendDiagnostic, readDiagnosticSummary } from "./diagnostics.mjs";
 import { readEvidence, summarizeEvidence } from "./evidence.mjs";
 import { readFollowUpQueue, summarizeFollowUpQueue } from "./follow-up-queue.mjs";
 import { readSteering, summarizeSteering } from "./steering.mjs";
@@ -141,6 +141,39 @@ function hostClaimActive(host) {
 	return Boolean(host && (host.state === "starting" || host.state === "alive" || host.state === "stopping"));
 }
 
+/**
+ * Views with an unrecovered host-meta contention report on record. The
+ * heartbeat path calls updateOwnedHost once per second, so without this a
+ * sustained contention episode would flood diagnostics.jsonl (issue #112).
+ */
+const hostMetaContentionReported = new Set();
+
+/** Test hook: clear the per-process contention report throttle. */
+export function clearHostMetaThrottleForTests() {
+	hostMetaContentionReported.clear();
+}
+
+/**
+ * Best-effort single warn per view per contention episode; diagnostics must
+ * never break the caller (appendDiagnostic throws on fs failure).
+ */
+function reportHostMetaContention(root, viewId, code, message, details) {
+	if (hostMetaContentionReported.has(viewId)) return;
+	hostMetaContentionReported.add(viewId);
+	try {
+		appendDiagnostic(root, viewId, { source: "store", level: "warn", code, message, details });
+	} catch { /* best effort */ }
+}
+
+/**
+ * Identity stamped on host-meta acquisitions so a holder that dies mid-hold
+ * leaves a reclaimable record (issue #112).
+ * @returns {{pid: number, startToken: string|null}}
+ */
+function hostMetaIdentity() {
+	return currentProcessIdentity();
+}
+
 /**
  * Atomically create the provisional `starting` host record for a new instance.
  * The ONLY entry point allowed to move "no claim / reclaimable terminal state"
@@ -149,13 +182,23 @@ function hostClaimActive(host) {
  * ready/stop fields so no stale owner data survives the handover.
  * @param {string} root
  * @param {Partial<HostStatus> & { viewId: string, instanceId: string }} provisionalHost
- * @param {{ heldStartLease?: unknown }} [opts] reserved for host-start lease nesting;
- *   host-meta is always acquired independently here (short critical section).
+ * @param {{ heldStartLease?: unknown, lockImpl?: typeof tryAcquireOwnedViewLock }} [opts]
+ *   heldStartLease is reserved for host-start lease nesting; lockImpl injects
+ *   the host-meta acquisition for deterministic contention/identity tests.
  * @returns {{ claimed: boolean, host: HostStatus|null }}
  */
 export function claimHost(root, provisionalHost, opts = {}) {
-	const lock = tryAcquireOwnedViewLock(root, provisionalHost.viewId, "host-meta");
-	if (!lock.acquired) return { claimed: false, host: null };
+	const acquireHostMeta = opts.lockImpl ?? tryAcquireOwnedViewLock;
+	const lock = acquireHostMeta(root, provisionalHost.viewId, "host-meta", { identity: hostMetaIdentity() });
+	if (!lock.acquired) {
+		// busy is ordinary millisecond-scale contention; blocked (identity-less
+		// holder) is the orphan-lock signature worth a diagnostic (issue #112).
+		if (lock.reason === "blocked") {
+			reportHostMetaContention(root, provisionalHost.viewId, "host_meta_claim_contended", "host-meta lease blocked; host claim not established", { reason: lock.reason });
+		}
+		return { claimed: false, host: null };
+	}
+	hostMetaContentionReported.delete(provisionalHost.viewId);
 	try {
 		const existing = readHost(root, provisionalHost.viewId);
 		if (hostClaimActive(existing)) return { claimed: false, host: existing };
@@ -213,12 +256,11 @@ export function claimHost(root, provisionalHost, opts = {}) {
  * few milliseconds, but a one-shot acquire can land inside that window and
  * return busy — a revoke or recovery write that silently no-ops is a real
  * reliability bug, not just a test race. Both `busy` (live owner) and
- * `blocked` (identity-less short hold — updateOwnedHost itself acquires
- * host-meta without a reclaimable identity, so concurrent fenced writes look
- * blocked to each other) are transient here: retry a few times with a short
- * synchronous sleep before giving up. A genuinely orphaned host-meta lock
- * (holder SIGKILLed mid-hold) survives the window and surfaces as retryable
- * not-updated — never as ownership loss.
+ * `blocked` (identity-less holder) are transient here: retry a few times with
+ * a short synchronous sleep before giving up, and record a warn diagnostic on
+ * a sustained episode (issue #112). Acquisitions stamp a full process identity
+ * (issue #112), so a holder that dies mid-hold leaves a reclaimable record;
+ * legacy identity-less residue is reclaimed past the orphan age gate.
  */
 const UPDATE_LOCK_BUSY_ATTEMPTS = 3;
 const UPDATE_LOCK_BUSY_SLEEP_MS = 20;
@@ -243,17 +285,21 @@ const UPDATE_LOCK_BUSY_SLEEP_MS = 20;
 export function updateOwnedHost(root, viewId, expectedInstanceId, mutate, opts = {}) {
 	const acquireHostMeta = opts.lockImpl ?? tryAcquireOwnedViewLock;
 	let lock;
+	let lastReason = null;
 	for (let attempt = 0; ; attempt++) {
-		lock = acquireHostMeta(root, viewId, "host-meta");
+		lock = acquireHostMeta(root, viewId, "host-meta", { identity: hostMetaIdentity() });
 		if (lock.acquired) break;
+		lastReason = lock.reason;
 		// busy and blocked are both millisecond-scale holds for host-meta;
 		// neither is ownership information — only the fenced read below is.
 		if (attempt >= UPDATE_LOCK_BUSY_ATTEMPTS - 1) {
+			reportHostMetaContention(root, viewId, "host_meta_lease_contended", "host-meta lease contended; fenced write not applied", { attempts: UPDATE_LOCK_BUSY_ATTEMPTS, lastReason });
 			return { updated: false, ownerChanged: false, host: null };
 		}
 		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, UPDATE_LOCK_BUSY_SLEEP_MS);
 	}
 	try {
+		hostMetaContentionReported.delete(viewId);
 		const host = readHost(root, viewId);
 		if (!host || !sameHostOwner(host, expectedInstanceId)) {
 			return { updated: false, ownerChanged: true, host };