@zhuxixi/pi-agent-board 0.4.2 → 0.5.0

package/docs/superpowers/specs/2026-08-30-post-exit-timing-fix-design.md

@@ -0,0 +1,80 @@
+# Spec: fix deterministic post-exit test failure after #43 (issue #46)
+
+## Problem
+
+`test/runner.integration.test.mjs` → `runner does not clobber a manual completion
+made during post-exit model passes` fails deterministically on Node 24 since
+#43 (`ffc2c8c`). Upstream `main` CI is red (`e14cc41`, `ffc2c8c`) and blocks
+subsequent PRs (#44).
+
+## Root cause (research: `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-46/`)
+
+#43 added a synchronous `updateCodeRefsFromEvidence()` call (git subprocesses,
+hundreds of ms) into `runner/job-runner.mjs`'s `persist()` chain, widening two
+pre-existing race windows:
+
+### Window 1 — `markCompleted` rejected (CI failure point)
+`persist()` order: `writeStatus` (endedAt visible) → `updateCodeRefsFromEvidence`
+(slow) → `writeState` (semanticState converges). The test sees `endedAt` while
+`state.json` is still `working`; the runner process is still alive
+(`pid.json` records the runner pid) → `isAgentBusy(row)` → `markCompleted`
+returns `'Wait for the active run to finish before marking done'`.
+
+### Window 2 — manual completion clobbered (the actual bug)
+`finalizeSemanticState` (`src/core/derive.mjs:33`) returns `"idle"` for a clean
+worker exit. `applyHeuristicAutoState` (`runner/job-runner.mjs:360`) calls
+`applyAutoStateToStatus` with the **in-memory** status; `isManualCompletion`
+requires `semanticState === "completed"` (it is `"idle"`), so the guard does not
+fire and the post-exit heuristic classification (`in_progress`, since
+`autoStateDoneDisabled()` defaults to true) overwrites the manual completion —
+`state.json` becomes `idle` + `autoState: {kind: "in_progress"}`.
+`maybeModelAutoState` has a fresh-read guard for this exact case;
+`applyHeuristicAutoState` does not.
+
+## Fix (minimal, four changes in `runner/job-runner.mjs`)
+
+### Change 1 — persist order
+Move `writeState` before `updateCodeRefsFromEvidence` inside `persist()`:
+```js
+writeStatus(root, status);
+writeRunEvidence(root, evidence);
+writeEvidence(root, evidence);
+writeState(root, projectViewState(status, now, readState(root, viewId)));
+updateCodeRefsFromEvidence(root, viewId, evidence, meta);
+```
+Semantics unchanged (code-refs extraction depends only on evidence + git).
+Verified experimentally: markCompleted assertion passes again.
+
+### Change 2 — heuristic persist goes through persistUnlessManual
+In the close handler, the `applyHeuristicAutoState` branch's `persist(true)`
+becomes `persistUnlessManual(true)` so a manual completion racing the
+heuristic classification is not overwritten. `persistUnlessManual` checks
+`isManualCompletion(readState(...))` (state.json — the only place
+`completeView` writes the `completed` + `autoState: null` signal; it only
+clears autoState in status.json) before writing.
+
+### Change 3 — applyHeuristicAutoState manual-completion guard
+Skip classification when state.json shows a manual completion, so the
+in-memory status isn't mutated in a way a later drain/persist could replay
+over the user's verdict:
+```js
+const latestState = readState(config.root, config.viewId);
+if (isManualCompletion(latestState)) return false;
+```
+
+### Change 4 — drainQueuedFollowUp / finalizeSteeringIfNeeded guards
+`drainQueuedFollowUp` (follow-up runs) and `finalizeSteeringIfNeeded`
+(plan approval resurrection) both early-return on
+`isManualCompletion(readState(...))` so the exit chain never starts new
+work or resurrects a row the user just manually completed.
+
+## Non-goals
+- No changes to #44/#45 code (windowsHide / control socket)
+- No handling of Windows-local EPERM cleanup noise (environment-only)
+- No auto-state state machine refactor
+
+## Verification
+1. clobber test ≥3× on Node 24: all pass (assertion part)
+2. Full `test/runner.integration.test.mjs`: failure set not worse than baseline
+3. `npm run typecheck` if present
+4. CI green (Node 22/24) after merge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
   "type": "module",
   "main": "./index.ts",
@@ -53,8 +53,9 @@
     "postinstall": "node scripts/patch-vulns.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node --test test/*.test.mjs",
+    "test:coverage": "c8 node --test test/*.test.mjs",
     "pack:dry": "npm pack --dry-run",
-    "verify": "npm run typecheck && npm test && npm run pack:dry"
+    "verify": "npm run typecheck && npm test && npm run test:coverage && npm run pack:dry"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -72,6 +73,7 @@
     "@earendil-works/pi-coding-agent": "0.79.8",
     "@earendil-works/pi-tui": "0.79.8",
     "@types/node": "^25.9.1",
+    "c8": "^12.0.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/runner/job-runner.mjs

@@ -16,11 +16,12 @@ import { encodePromptForCliArg } from "../src/core/prompt-transport.mjs";
 import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { emptyEvidenceSnapshot, finalizeEvidence, reduceEvidence, summarizeEvidence, writeEvidence, writeRunEvidence } from "../src/core/evidence.mjs";
+import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
 import { claimNextFollowUp, completeFollowUp, releaseFollowUp } from "../src/core/follow-up-queue.mjs";
 import { newRunId } from "../src/core/ids.mjs";
 import { launchRun } from "../src/core/launch.mjs";
 import * as P from "../src/core/paths.mjs";
-import { readState, readStatus, writeState, writeStatus } from "../src/core/store.mjs";
+import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
 import { readSteering, recordPlanReady } from "../src/core/steering.mjs";
 import { buildApprovePlanPrompt, buildPlanChangesPrompt, buildPlanRequestPrompt } from "../src/core/steering-prompts.mjs";
 
@@ -54,12 +55,16 @@ function main() {
 	const stderrLog = P.stderrPath(root, viewId, runId);
 	const eventsLog = P.eventsPath(root, viewId, runId);
 
+	// Read the view meta once so code-ref extraction reuses it across every evidence write.
+	const meta = readMeta(root, viewId);
+
 	let status = createRunStatus(config, null, Date.now());
 	let evidence = emptyEvidenceSnapshot({ viewId, runId, source: "json-runner" });
 	appendDiagnostic(root, viewId, { source: "runner", runId, code: "runner_start", message: "Runner started", details: { kind: config.kind, cwd: config.cwd, model: config.model } });
 	writeStatus(root, status);
 	writeRunEvidence(root, evidence);
 	writeEvidence(root, evidence);
+	updateCodeRefsFromEvidence(root, viewId, evidence, meta);
 	writeState(root, projectViewState(status, Date.now(), readState(root, viewId)));
 
 	// Build worker args: pi --mode json -p --session <file> [--model m] [--thinking l] [--tools t] <prompt>
@@ -80,6 +85,7 @@ function main() {
 	const worker = spawn(config.piCommand, args, {
 		cwd: config.cwd,
 		stdio: ["ignore", "pipe", "pipe"],
+		windowsHide: true,
 		env: process.env,
 	});
 
@@ -99,6 +105,10 @@ function main() {
 		writeRunEvidence(root, evidence);
 		writeEvidence(root, evidence);
 		writeState(root, projectViewState(status, now, readState(root, viewId)));
+		// Best-effort code-refs extraction shells out to git and can take hundreds of
+		// ms; run it after the state write so endedAt-visible state converges first.
+		// The extraction only depends on evidence + git, never on state.json.
+		updateCodeRefsFromEvidence(root, viewId, evidence, meta);
 		dirty = false;
 	};
 
@@ -212,7 +222,7 @@ function main() {
 		if (applyHeuristicAutoState(config, status, evidence)) {
 			finalizeEvidence(evidence, status, Date.now());
 			status.evidenceSummary = summarizeEvidence(evidence);
-			persist(true);
+			persistUnlessManual(true);
 		}
 		maybeModelAutoState(config, status, evidence)
 			.then((changed) => {
@@ -228,8 +238,18 @@ function main() {
 			})
 			.catch(() => {})
 			.finally(() => {
-				finalizeSteeringIfNeeded(config, status, evidence);
-				drainQueuedFollowUp(config, status);
+				// The finalize chain must never prevent process.exit: a lock/fs failure
+				// here used to pin the runner as a 100% CPU zombie (issue #33).
+				try {
+					finalizeSteeringIfNeeded(config, status, evidence);
+				} catch (err) {
+					tryAppendDiagnostic(config, "finalize_steering_failed", err);
+				}
+				try {
+					drainQueuedFollowUp(config, status);
+				} catch (err) {
+					tryAppendDiagnostic(config, "follow_up_drain_failed", err);
+				}
 				process.exit(stoppedByUser ? 0 : (code ?? 0));
 			});
 	});
@@ -239,6 +259,10 @@ function main() {
 function finalizeSteeringIfNeeded(config, status, evidence) {
 	if (config.kind !== "plan" && config.kind !== "plan_change") return;
 	if (status.semanticState === "failed" || status.semanticState === "stopped") return;
+	// A manual completion racing the exit chain must not be resurrected for
+	// approval: the user already closed this row. Same signal as the other
+	// post-exit guards (completeView writes completed+autoState null to state.json).
+	if (isManualCompletion(readState(config.root, config.viewId))) return;
 	recordPlanReady(config.root, config.viewId, {
 		runId: config.runId,
 		planText: latestEvidenceText(evidence) || status.latestAssistantPreview || status.summary || "Plan ready",
@@ -259,6 +283,11 @@ function finalizeSteeringIfNeeded(config, status, evidence) {
 /** @param {import("../src/core/types.mjs").RunConfig} config @param {import("../src/core/types.mjs").RunStatus} status */
 function drainQueuedFollowUp(config, status) {
 	if (status.semanticState !== "idle" && status.semanticState !== "completed") return;
+	// A manual completion racing the exit chain must never be followed up: the
+	// user just finished this row, so don't launch a new run over it. The
+	// in-memory status may be stale (fresh-read guards skip classification), so
+	// check the authoritative state.json signal.
+	if (isManualCompletion(readState(config.root, config.viewId))) return;
 	if (config.kind === "plan" || config.kind === "plan_change") return;
 	const claimed = claimNextFollowUp(config.root, config.viewId);
 	if (!claimed.ok || !claimed.item) return;
@@ -283,6 +312,22 @@ function drainQueuedFollowUp(config, status) {
 	}
 }
 
+/** @param {import("../src/core/types.mjs").RunConfig} config @param {string} code @param {unknown} err */
+function tryAppendDiagnostic(config, code, err) {
+	try {
+		appendDiagnostic(config.root, config.viewId, {
+			source: "runner",
+			runId: config.runId,
+			level: "error",
+			code,
+			message: "Finalize step failed",
+			details: { error: err instanceof Error ? err.message : String(err) },
+		});
+	} catch {
+		/* root may be deleted — nothing to persist, exit anyway */
+	}
+}
+
 /** @param {import("../src/core/types.mjs").FollowUpItem} item */
 function runKindForFollowUp(item) {
 	switch (item.kind) {
@@ -326,6 +371,13 @@ function canAutoState(config, status, evidence) {
 
 function applyHeuristicAutoState(config, status, evidence) {
 	if (!canAutoState(config, status, evidence)) return false;
+	// Fresh read of state.json (not status.json): completeView writes the manual
+	// completion signal (semanticState "completed" + autoState null) to state.json
+	// and only clears autoState in status.json, so status.json can never carry
+	// the completed+null pair. If the user marked the row done while the worker
+	// was exiting, skip classification so the persist path can't clobber it.
+	const latestState = readState(config.root, config.viewId);
+	if (isManualCompletion(latestState)) return false;
 	const latest = latestEvidenceText(evidence) || status.latestAssistantPreview || status.summary || "";
 	const classification = heuristicAutoState(latest, { lastAgentActivityAt: status.lastAgentActivityAt ?? null });
 	const changed = applyAutoStateToStatus(status, classification, Date.now());
@@ -408,7 +460,7 @@ async function maybeModelSummary(config, status) {
 function runOneShot(command, args, timeoutMs = 20000) {
 	return new Promise((resolve) => {
 		let out = "";
-		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
 		let buf = "";
 		child.stdout.on("data", (c) => {
 			buf += c.toString();

package/runner/pty-runner.mjs

@@ -11,7 +11,11 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { existsSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
+import { appendDiagnostic } from "../src/core/diagnostics.mjs";
+import { finalizeHostCrash } from "../src/core/host-crash.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";
@@ -54,8 +58,14 @@ function main() {
 	/** @type {Set<import("node:net").Socket>} */
 	const clients = new Set();
 	let childPid = null;
+	let child = null;
 	let exitCode = null;
 	let stopping = false;
+	// Set when the uncaughtException crash handler finalizes the host. Guards
+	// child.onExit against clobbering the persisted "failed" state with an
+	// "exited" update (the handler kills the child, so its exit callback fires
+	// inside the 50ms flush window — CR round-1, issue #48).
+	let crashed = false;
 	/** @type {import("../src/core/types.mjs").HostStatus} */
 	let host = {
 		version: 1,
@@ -75,7 +85,24 @@ function main() {
 		attachedClients: 0,
 		attachedEver: false,
 	};
-	const persist = () => writeHost(config.root, host);
+	/** Persist host.json. A transient failure (e.g. Windows rename EPERM racing a
+	 *  reader) must degrade, not kill the host: record a diagnostic and let the
+	 *  next heartbeat tick retry. Socket protocol is the attach main channel, so
+	 *  host.json being briefly stale is acceptable. */
+	const persist = () => {
+		try {
+			writeHost(config.root, host);
+		} catch (err) {
+			try {
+				appendDiagnostic(config.root, config.viewId, {
+					source: "runner",
+					level: "error",
+					code: "persist_error",
+					message: err instanceof Error ? err.message : String(err),
+				});
+			} catch { /* diagnostics must never kill the host either */ }
+		}
+	};
 	const broadcast = (msg) => {
 		const line = JSON.stringify(msg) + "\n";
 		for (const c of clients) c.write(line);
@@ -87,6 +114,32 @@ function main() {
 	};
 	persist();
 
+	// Last-resort crash path (registered early, before spawnInteractive, so any
+	// early synchronous failure is also covered): the runner is launched detached
+	// with stdio ignored, so an uncaught exception is otherwise completely silent —
+	// no host.json finalize, no exit message, and the attach view reconnects
+	// forever. Record diagnostics, finalize the host as failed, and broadcast exit
+	// so attached clients can leave the view instead of looping.
+	process.on("uncaughtException", (err) => {
+		process.removeAllListeners("uncaughtException");
+		try {
+			appendDiagnostic(config.root, config.viewId, {
+				source: "runner",
+				level: "error",
+				code: "runner_crash",
+				message: err instanceof Error ? err.message : String(err),
+				details: { stack: err instanceof Error ? err.stack : undefined },
+			});
+		} catch { /* best effort */ }
+		crashed = true;
+		host = finalizeHostCrash(config.root, config.viewId, host, err);
+		try {
+			broadcast({ type: "exit", exitCode: 1 });
+		} catch { /* best effort */ }
+		try { if (child) killChild(child, childPid, "SIGTERM"); } catch { /* best effort */ }
+		setTimeout(() => process.exit(1), 50).unref?.();
+	});
+
 	const args = [...config.piArgsPrefix, "--session", config.sessionFile];
 	if (config.model) args.push("--model", config.model);
 	if (config.thinkingLevel) args.push("--thinking", config.thinkingLevel);
@@ -107,7 +160,6 @@ function main() {
 		AGENT_VIEW_HOSTED: "pty",
 	};
 
-	let child;
 	try {
 		child = spawnInteractive(config.piCommand, args, {
 			cwd: config.cwd,
@@ -123,7 +175,7 @@ function main() {
 		process.exit(1);
 	}
 	childPid = child.pid ?? null;
-	update({ childPid, state: "alive" });
+	update({ childPid });
 
 	child.onData((data) => {
 		screenLogBytes = appendBoundedScreenLog(screenLog, data, screenLogBytes, screenLogLimits);
@@ -131,8 +183,12 @@ function main() {
 	});
 	child.onExit((code) => {
 		exitCode = code ?? 0;
-		update({ state: stopping ? "exited" : "exited", endedAt: Date.now(), exitCode, childPid: null });
-		broadcast({ type: "exit", exitCode });
+		// After a crash the handler already persisted "failed" and broadcast
+		// exit; this callback must not overwrite that state.
+		if (!crashed) {
+			update({ state: stopping ? "exited" : "exited", endedAt: Date.now(), exitCode, childPid: null });
+			broadcast({ type: "exit", exitCode });
+		}
 		setTimeout(() => process.exit(exitCode ?? 0), 50).unref?.();
 	});
 	child.onError((err) => {
@@ -163,7 +219,7 @@ function main() {
 	});
 	server.on("error", (err) => {
 		update({ state: "failed", endedAt: Date.now(), error: err instanceof Error ? err.message : String(err), exitCode: 1 });
-		try { child.kill("SIGTERM"); } catch {}
+		killChild(child, childPid, "SIGTERM");
 		process.exit(1);
 	});
 	server.listen(socketPath, () => update({ socketPath, state: "alive" }));
@@ -189,11 +245,12 @@ function main() {
 			case "interrupt":
 				child.write("\x1b");
 				break;
-			case "terminate":
+			case "terminate": {
 				stopping = true;
-				child.kill("SIGTERM");
-				setTimeout(() => child.kill("SIGKILL"), 4000).unref?.();
+				killChild(child, childPid, "SIGTERM");
+				setTimeout(() => killChild(child, childPid, "SIGKILL"), 4000).unref?.();
 				break;
+			}
 			case "detach":
 				socket.end();
 				break;
@@ -212,7 +269,7 @@ function main() {
 		stopping = true;
 		try { server.close(); } catch {}
 		try { if (existsSync(socketPath)) unlinkSync(socketPath); } catch {}
-		try { child.kill("SIGTERM"); } catch {}
+		killChild(child, childPid, "SIGTERM");
 		setTimeout(() => process.exit(0), 100).unref?.();
 	};
 	process.on("SIGTERM", shutdown);
@@ -245,7 +302,7 @@ function spawnInteractive(command, args, opts) {
 	}
 	if (!opts.allowPipeFallback) throw new Error("node-pty is unavailable");
 
-	const proc = spawn(command, args, { cwd: opts.cwd, env: opts.env, stdio: ["pipe", "pipe", "pipe"] });
+	const proc = spawn(command, args, { cwd: opts.cwd, env: opts.env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
 	return {
 		pid: proc.pid ?? null,
 		write: (s) => proc.stdin.write(s),
@@ -264,6 +321,26 @@ function send(socket, msg) {
 	socket.write(JSON.stringify(msg) + "\n");
 }
 
+/**
+ * Terminate the hosted child on all platforms. node-pty's kill() throws
+ * "Signals not supported on windows", so on win32 we TerminateProcess via
+ * process.kill; on unix keep the graceful SIGTERM/SIGKILL path through the pty.
+ * @param {{ kill: (signal: string) => void }} child
+ * @param {number|null} pid
+ * @param {"SIGTERM"|"SIGKILL"} [signal]
+ */
+function killChild(child, pid, signal = "SIGTERM") {
+	if (process.platform === "win32") {
+		if (pid) {
+			try {
+				process.kill(pid, "SIGKILL");
+				return;
+			} catch {}
+		}
+	}
+	try { child.kill(signal); } catch {}
+}
+
 function clampInt(value, min, max, fallback) {
 	const n = Number(value);
 	if (!Number.isFinite(n)) return fallback;
@@ -302,7 +379,7 @@ function markRowFailed(root, viewId, message) {
 }
 
 function failEarly(message) {
-	try { appendLine("/tmp/pi-agent-board-pty-runner.err", message); } catch {}
+	try { appendLine(join(tmpdir(), "pi-agent-board-pty-runner.err"), message); } catch {}
 	process.stderr.write(`${message}\n`);
 	process.exit(2);
 }

package/runner/state-runner.mjs

@@ -11,7 +11,8 @@ 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 { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from "../src/core/evidence.mjs";
-import { readState, readStatus, writeState, writeStatus } from "../src/core/store.mjs";
+import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
+import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
 
 async function main() {
 	const configPath = process.argv[2];
@@ -20,6 +21,9 @@ async function main() {
 	const config = readJson(configPath, null);
 	if (!config || !autoStateEnabled()) process.exit(0);
 
+	// Read the view meta once so code-ref extraction reuses it on the evidence write.
+	const meta = readMeta(config.root, config.viewId);
+
 	const state = readState(config.root, config.viewId);
 	if (!state || state.processState === "alive" || state.semanticState === "failed" || state.semanticState === "stopped") process.exit(0);
 
@@ -55,6 +59,7 @@ async function main() {
 	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 } });
@@ -86,7 +91,7 @@ function runOneShot(command, args, opts = {}) {
 	return new Promise((resolve) => {
 		let out = "";
 		let settled = false;
-		const child = spawn(command, args, { cwd: opts.cwd, env: opts.env ?? process.env, stdio: ["ignore", "pipe", "ignore"] });
+		const child = spawn(command, args, { cwd: opts.cwd, env: opts.env ?? process.env, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
 		let buf = "";
 		const finish = () => {
 			if (settled) return;

package/runner/title-runner.mjs

@@ -45,7 +45,7 @@ async function maybeGenerateTitle(config) {
 function runOneShot(command, args, timeoutMs = 20000) {
 	return new Promise((resolve) => {
 		let out = "";
-		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
 		let buf = "";
 		child.stdout.on("data", (c) => {
 			buf += c.toString();

package/src/core/atomic.mjs

@@ -16,11 +16,50 @@ import {
 } from "node:fs";
 import * as path from "node:path";
 
+/** Retry backoff (ms) for rename retries; index i is the delay after attempt i. */
+export const RENAME_RETRY_BACKOFF_MS = [10, 50, 250];
+/** Error codes that mean "transient sharing violation" — retryable on Windows. */
+export const RENAME_RETRY_ERROR_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
+
 /** @param {string} dir */
 export function ensureDir(dir) {
 	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
+/**
+ * rename() with retries for Windows sharing-violation races.
+ *
+ * On Windows, libuv opens files without FILE_SHARE_DELETE, so replacing an
+ * existing target while any other process holds it open for reading throws
+ * EPERM/EBUSY/EACCES. The reader window is microseconds, so a few retries
+ * with a short backoff succeed almost always. Non-whitelisted errors
+ * (e.g. EISDIR) are configuration errors and throw immediately.
+ * @param {string} tmp
+ * @param {string} file
+ * @param {{ rename?: (a: string, b: string) => void, delays?: number[], errorCodes?: Set<string> }} [opts]
+ */
+export function renameWithRetry(tmp, file, opts = {}) {
+	const rename = opts.rename ?? renameSync;
+	const delays = opts.delays ?? RENAME_RETRY_BACKOFF_MS;
+	const errorCodes = opts.errorCodes ?? RENAME_RETRY_ERROR_CODES;
+	for (let attempt = 0; ; attempt++) {
+		try {
+			rename(tmp, file);
+			return;
+		} catch (err) {
+			const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+			if (!errorCodes.has(code) || attempt >= delays.length) {
+				// Exhausted or non-transient: leave no .tmp litter behind, then
+				// surface the original error so callers can degrade deliberately.
+				try { unlinkSync(tmp); } catch { /* best effort */ }
+				throw err;
+			}
+		}
+		// Synchronous sleep (Atomics.wait) — atomicWrite is a sync API.
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delays[attempt]);
+	}
+}
+
 /**
  * Atomically write a string to `file` (creates parent dirs).
  * @param {string} file
@@ -30,7 +69,7 @@ export function atomicWrite(file, data) {
 	ensureDir(path.dirname(file));
 	const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
 	writeFileSync(tmp, data, "utf8");
-	renameSync(tmp, file);
+	renameWithRetry(tmp, file);
 }
 
 /**