@zhuxixi/pi-agent-board 0.4.2 → 0.4.3

package/README.md

@@ -101,6 +101,7 @@ If the board reports `node-pty unavailable`, press `!` in the dashboard for diag
 npm install
 npm run typecheck
 npm test
+npm run test:coverage
 npm run pack:dry
 ```
 
@@ -110,7 +111,20 @@ Run all checks with:
 npm run verify
 ```
 
-`npm run verify` runs typecheck, tests, and a dry npm pack.
+`npm run verify` runs typecheck, tests, coverage, and a dry npm pack.
+
+### QA baseline
+
+Every push and PR runs the same checks in CI (`.github/workflows/ci.yml`, Node 22 + 24),
+and `main` branch protection requires both CI checks to pass before merging.
+
+Coverage is enforced by `c8` with thresholds configured in `.c8rc.json`
+(lines ≥ 85%, functions ≥ 80%, branches ≥ 70%). The TS UI layer
+(`src/ui/*.ts`, `src/commands/*.ts`) is covered by a smoke test
+(`test/ui-smoke.test.mjs`) that constructs and renders the real entrypoints;
+it is excluded from the coverage thresholds by design.
+
+Current baseline: 300+ tests, ~92% line coverage on the core modules.
 
 ## Publish
 

package/docs/superpowers/plans/2026-08-27-locks-acquirelock-spin.md

@@ -0,0 +1,614 @@
+# locks.mjs Bounded Acquisition Fix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `acquireLock` in `src/core/locks.mjs` fail fast (bounded attempts → throw) instead of spinning forever when the lock can never be acquired, and harden every layer above it (queue, runner, test harness) so a lock failure can never produce a 100%-CPU zombie process again (issue #33).
+
+**Architecture:** Four defense layers. (1) `locks.mjs`: classify acquisition failures — EEXIST contention keeps the existing wait-window + force-steal semantics (bounded to 2 steal attempts), all other errors (ENOENT/EACCES/ENOTDIR/EROFS/ENOSPC…) get 3 quick retries with `ensureDir` re-run for self-heal, then throw. (2) `follow-up-queue.mjs` catches any throw and returns `{ok:false, error}` per the module's existing convention. (3) `runner/job-runner.mjs` wraps the post-exit finalize chain in try/catch so `process.exit` always runs. (4) `test/runner.integration.test.mjs` kills every detached runner in teardown before deleting the root.
+
+**Tech Stack:** Node 24 ESM (`.mjs`), `node:test` + `node:assert/strict`, sync `node:fs`, tabs indentation, JSDoc types, zero new dependencies.
+
+## Global Constraints
+
+- **Worktree only:** all file paths below are relative to `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-33-locks-acquirelock-spin` — never touch the main checkout.
+- **Existing semantics must not change:** the 5 existing tests in `test/locks.test.mjs` stay unmodified and green (wait-window contention + stale steal + force-steal-after-window are contract).
+- Every new test carries `{ timeout: 5000 }` so a regression to a spin loop fails fast instead of hanging the suite.
+- fs injection follows the `defaultScreenLogFs` precedent in `src/core/screen-log.mjs` (frozen object of raw `node:fs` functions passed via opts).
+- Stage by explicit file path (`git add <file>`), never `git add -A`.
+- Conventional commits, English messages. Comments in English, tabs for indentation.
+- Test command: `npm test` (= `node --test test/*.test.mjs`). Final gate: `npm run verify`.
+- `appendLine`/`appendDiagnostic` are NOT best-effort (verified: `ensureDir` + `appendFileSync` throw on deleted roots) — any diagnostic call on a possibly-dead root must be wrapped.
+
+---
+
+### Task 1: locks.mjs — bounded acquisition, error classification, fs injection
+
+**Files:**
+- Modify: `src/core/locks.mjs` (full rewrite of internals, same public API + new opts)
+- Test: `test/locks.test.mjs` (append new tests; do not modify existing 5)
+
+**Interfaces:**
+- Consumes: `ensureDir(dir)` from `src/core/atomic.mjs`; `P.viewLockPath(root, viewId, name)`.
+- Produces (other tasks rely on these):
+  - `withFileLockSync(lockPath, fn, opts?)` — `opts.fs` (frozen `{existsSync, mkdirSync, readFileSync, rmSync, writeFileSync}`, default `defaultLocksFs`), `opts.staleMs` (default 30000). Throws `Error` with `err.code === "LOCK_TIMEOUT"` and message containing the lockPath when acquisition is impossible.
+  - `withViewLockSync(root, viewId, name, fn, opts?)` — passes opts through.
+  - `defaultLocksFs` exported (for tests).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/locks.test.mjs` (also add `defaultLocksFs` to the import from `../src/core/locks.mjs`, and `writeFileSync` to the existing `node:fs` import — it is already there for the stale-lock tests, verify):
+
+```js
+const LOCK_FS = defaultLocksFs;
+
+function eexist() {
+	const e = new Error("EEXIST");
+	e.code = "EEXIST";
+	return e;
+}
+
+test("withFileLockSync throws promptly when mkdirSync keeps failing", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const fs = {
+			...LOCK_FS,
+			mkdirSync: (p, o) => {
+				const e = new Error("EACCES");
+				e.code = "EACCES";
+				throw e;
+			},
+		};
+		const started = Date.now();
+		assert.throws(
+			() => withFileLockSync(join(root, "x.lock"), () => "no", { fs }),
+			/lock path unusable/,
+		);
+		assert.ok(Date.now() - started < 2000, "must fail fast, not spin");
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("withFileLockSync throws and cleans up when owner.json writes keep failing", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const fs = {
+			...LOCK_FS,
+			writeFileSync: (file, data, opts) => {
+				if (String(file).endsWith("owner.json")) {
+					const e = new Error("ENOSPC");
+					e.code = "ENOSPC";
+					throw e;
+				}
+				return LOCK_FS.writeFileSync(file, data, opts);
+			},
+		};
+		assert.throws(
+			() => withFileLockSync(join(root, "w.lock"), () => "no", { fs }),
+			/lock path unusable/,
+		);
+		assert.equal(existsSync(join(root, "w.lock")), false, "half-created lock must be cleaned up");
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("withFileLockSync throws after bounded steal attempts when rmSync keeps failing", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const lockPath = join(root, "s.lock");
+		mkdirSync(lockPath);
+		writeFileSync(join(lockPath, "owner.json"), JSON.stringify({ pid: 1, at: Date.now() - 60_000 }), "utf8"); // stale
+		const fs = {
+			...LOCK_FS,
+			rmSync: (p, o) => {
+				const e = new Error("EPERM");
+				e.code = "EPERM";
+				throw e;
+			},
+		};
+		const started = Date.now();
+		assert.throws(
+			() => withFileLockSync(lockPath, () => "no", { fs, staleMs: 50 }),
+			/stale lock could not be stolen/,
+		);
+		assert.ok(Date.now() - started < 2000);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("withFileLockSync waits through transient contention and acquires", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const lockPath = join(root, "c.lock");
+		mkdirSync(lockPath);
+		writeFileSync(join(lockPath, "owner.json"), JSON.stringify({ pid: 1, at: Date.now() }), "utf8"); // fresh holder
+		let eexistLeft = 3;
+		const fs = {
+			...LOCK_FS,
+			mkdirSync: (p, o) => {
+				if (p === lockPath && eexistLeft-- > 0) throw eexist();
+				if (p === lockPath) LOCK_FS.rmSync(lockPath, { recursive: true, force: true }); // holder releases
+				return LOCK_FS.mkdirSync(p, o);
+			},
+		};
+		const started = Date.now();
+		const result = withFileLockSync(lockPath, () => "won", { fs, staleMs: 30_000 });
+		assert.equal(result, "won");
+		assert.ok(Date.now() - started >= 40, "should have slept through contention ticks");
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("withFileLockSync self-heals a parent dir deleted mid-acquisition", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const lockPath = join(root, "del", "parent", "p.lock");
+		let failedOnce = false;
+		const fs = {
+			...LOCK_FS,
+			mkdirSync: (p, o) => {
+				if (p === lockPath && !failedOnce) {
+					failedOnce = true; // simulate parent deleted between ensureDir and mkdir
+					const e = new Error("ENOENT");
+					e.code = "ENOENT";
+					throw e;
+				}
+				return LOCK_FS.mkdirSync(p, o);
+			},
+		};
+		const result = withFileLockSync(lockPath, () => "healed", { fs });
+		assert.equal(result, "healed");
+		assert.equal(existsSync(lockPath), false);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("lock timeout errors carry LOCK_TIMEOUT code and the lock path", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const fs = {
+			...LOCK_FS,
+			mkdirSync: (p, o) => {
+				const e = new Error("EROFS");
+				e.code = "EROFS";
+				throw e;
+			},
+		};
+		const lockPath = join(root, "code.lock");
+		assert.throws(
+			() => withFileLockSync(lockPath, () => "no", { fs }),
+			(err) => err.code === "LOCK_TIMEOUT" && String(err.message).includes(lockPath),
+		);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- --test-name-pattern "withFileLockSync (throws|waits|self-heals)|lock timeout"`
+Expected: the spin-path tests (`mkdirSync keeps failing`, `self-heals`) FAIL via the 5000ms timeout (current code spins forever); the rmSync-steal test fails by timeout too; `owner.json writes` may fail by timeout. RED confirmed.
+
+- [ ] **Step 3: Implement the new locks.mjs**
+
+Replace `src/core/locks.mjs` with:
+
+```js
+/**
+ * Tiny dependency-free synchronous file lock helpers for local agent-board artifacts.
+ * Locks use atomic mkdir on a sibling .lock directory and are cleaned up in finally.
+ *
+ * Failure model (issue #33): acquisition failures are classified.
+ * - EEXIST (contention): wait in 20ms ticks until the stale window passes, then
+ *   force-steal (bounded to MAX_STEAL_ATTEMPTS). This preserves the original
+ *   wait/steal contract (see test/locks.test.mjs).
+ * - Anything else (deleted parent, read-only fs, permissions, disk full, ...):
+ *   MAX_ENV_ATTEMPTS quick retries — each retry re-runs ensureDir so a parent
+ *   deleted mid-acquisition self-heals — then throw LOCK_TIMEOUT. Never spin.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { ensureDir } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+
+const DEFAULT_STALE_MS = 30_000;
+/** Minimum contention window before a fresh lock can be force-stolen. */
+const MIN_WINDOW_MS = 250;
+const WAIT_TICK_MS = 20;
+/** Max stale-lock steal attempts before giving up. */
+const MAX_STEAL_ATTEMPTS = 2;
+/** Max quick retries for environmental failures before giving up. */
+const MAX_ENV_ATTEMPTS = 3;
+
+export const defaultLocksFs = Object.freeze({ existsSync, mkdirSync, readFileSync, rmSync, writeFileSync });
+
+/**
+ * @template T
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
+ * @returns {T}
+ */
+export function withFileLockSync(lockPath, fn, opts = {}) {
+	const fs = opts.fs ?? defaultLocksFs;
+	acquireLock(lockPath, opts.staleMs ?? DEFAULT_STALE_MS, fs);
+	let result;
+	try {
+		result = fn();
+	} finally {
+		releaseLock(lockPath, fs);
+	}
+	return result;
+}
+
+/**
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} name
+ * @param {() => T} fn
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
+ * @returns {T}
+ */
+export function withViewLockSync(root, viewId, name, fn, opts = {}) {
+	return withFileLockSync(P.viewLockPath(root, viewId, name), fn, opts);
+}
+
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function acquireLock(lockPath, staleMs, fs) {
+	const deadline = Date.now() + Math.max(MIN_WINDOW_MS, staleMs);
+	let steals = 0;
+	let envAttempts = 0;
+	for (;;) {
+		let created = false;
+		try {
+			// Re-run every attempt: a parent deleted mid-acquisition self-heals here.
+			ensureDir(path.dirname(lockPath));
+			fs.mkdirSync(lockPath);
+			created = true;
+			fs.writeFileSync(
+				path.join(lockPath, "owner.json"),
+				JSON.stringify({ pid: process.pid, at: Date.now() }),
+				"utf8",
+			);
+			return;
+		} catch (err) {
+			if (err && err.code === "EEXIST") {
+				const expired = Date.now() >= deadline;
+				if (isLockStale(lockPath, staleMs, fs) || expired) {
+					if (steals >= MAX_STEAL_ATTEMPTS) {
+						throw lockError(lockPath, `stale lock could not be stolen after ${steals} attempts`);
+					}
+					steals += 1;
+					releaseLock(lockPath, fs);
+					continue;
+				}
+				sleep(WAIT_TICK_MS);
+				continue;
+			}
+			// Environmental failure: bounded quick retries, then fail fast.
+			if (created) releaseLock(lockPath, fs);
+			envAttempts += 1;
+			if (envAttempts >= MAX_ENV_ATTEMPTS) {
+				const reason = (err && (err.code || err.message)) || "unknown error";
+				throw lockError(lockPath, `lock path unusable (${reason})`);
+			}
+			sleep(WAIT_TICK_MS);
+		}
+	}
+}
+
+/** @param {string} lockPath @param {string} reason */
+function lockError(lockPath, reason) {
+	const err = new Error(`file lock unavailable: ${lockPath} (${reason})`);
+	err.code = "LOCK_TIMEOUT";
+	return err;
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function isLockStale(lockPath, staleMs, fs) {
+	try {
+		if (!fs.existsSync(lockPath)) return false;
+		const raw = fs.readFileSync(path.join(lockPath, "owner.json"), "utf8");
+		const owner = JSON.parse(raw);
+		return Date.now() - Number(owner.at ?? 0) > staleMs;
+	} catch {
+		return true;
+	}
+}
+
+/** @param {string} lockPath @param {typeof defaultLocksFs} fs */
+function releaseLock(lockPath, fs) {
+	try {
+		fs.rmSync(lockPath, { recursive: true, force: true });
+	} catch {
+		/* best effort */
+	}
+}
+```
+
+- [ ] **Step 4: Run tests to verify green**
+
+Run: `npm test -- --test-name-pattern "withFileLockSync|withViewLockSync|lock timeout"`
+Expected: ALL PASS — the 5 existing tests unmodified plus the 6 new ones.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/locks.mjs test/locks.test.mjs
+git commit -m "fix: bound lock acquisition with error classification and fs injection (issue #33)"
+```
+
+---
+
+### Task 2: follow-up-queue.mjs — catch-all {ok:false} translation
+
+**Files:**
+- Modify: `src/core/follow-up-queue.mjs` (route all 5 lock sites through one guarded helper)
+- Test: `test/follow-up-queue.test.mjs` (append)
+
+**Interfaces:**
+- Consumes: Task 1's `withViewLockSync(root, viewId, name, fn, opts?)` (throws `LOCK_TIMEOUT` on failure).
+- Produces: unchanged public signatures; NEW behavior — every mutating queue op (`enqueueFollowUp`, `claimNextFollowUp`, `completeFollowUp`, `failFollowUp`, `releaseFollowUp`, `removeLastFollowUp`, `clearQueuedFollowUps`) returns `{ok:false, error}` instead of throwing when the lock (or any fs op inside fn) fails. `service.mjs` and `runner/job-runner.mjs` consume the `{ok}` convention unchanged.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/follow-up-queue.test.mjs` (add `writeFileSync` to the `node:fs` import):
+
+```js
+test("queue ops return {ok:false} when the lock path is unusable", { timeout: 5000 }, () => {
+	const root = freshRoot();
+	try {
+		const fileRoot = join(root, "notadir");
+		writeFileSync(fileRoot, "x", "utf8"); // ensureDir under a file path -> ENOTDIR, unrecoverable
+		const enq = enqueueFollowUp(fileRoot, "v1", "hello");
+		assert.equal(enq.ok, false);
+		assert.match(String(enq.error), /lock unavailable/);
+		const claim = claimNextFollowUp(fileRoot, "v1");
+		assert.equal(claim.ok, false);
+		assert.match(String(claim.error), /lock unavailable/);
+		const removed = removeLastFollowUp(fileRoot, "v1");
+		assert.equal(removed.ok, false);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npm test -- --test-name-pattern "lock path is unusable"`
+Expected: FAIL — current code propagates the raw ENOTDIR throw (uncaught error fails the test).
+
+- [ ] **Step 3: Implement**
+
+In `src/core/follow-up-queue.mjs`: add a guarded wrapper after the imports and route the 5 `withViewLockSync(...)` call sites (`enqueueFollowUp`, `claimNextFollowUp`, `removeLastFollowUp`, `clearQueuedFollowUps`, and the private `updateItem`) through it — replace each `return withViewLockSync(root, viewId, "queue", () => { ... })` with `return lockedQueueOp(root, viewId, () => { ... })` (body unchanged):
+
+```js
+import { withViewLockSync } from "./locks.mjs";
+// ...existing imports...
+
+/**
+ * Run a queue mutation under the view lock, translating any failure (lock
+ * unavailable, fs errors inside the mutation) into {ok:false} so callers on
+ * the {ok} convention never see a throw (issue #33).
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {() => T} fn
+ * @returns {T | { ok: false, error: string }}
+ */
+function lockedQueueOp(root, viewId, fn) {
+	try {
+		return withViewLockSync(root, viewId, "queue", fn);
+	} catch (err) {
+		return { ok: false, error: `follow-up queue lock unavailable: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}
+```
+
+- [ ] **Step 4: Run the full queue suite**
+
+Run: `npm test -- --test-name-pattern "follow-up|queue"`
+Expected: ALL PASS (existing FIFO/durability tests + the new one).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/follow-up-queue.mjs test/follow-up-queue.test.mjs
+git commit -m "fix: translate follow-up queue lock failures into {ok:false} results (issue #33)"
+```
+
+---
+
+### Task 3: job-runner.mjs — finalize chain can never skip process.exit
+
+**Files:**
+- Modify: `runner/job-runner.mjs` (the `worker.on("close")` `.finally` block only)
+
+**Interfaces:**
+- Consumes: Task 2's `{ok:false}` queue results (`claimNextFollowUp` no longer throws on lock failure — the existing `if (!claimed.ok || !claimed.item) return;` already handles it).
+- Produces: no signature changes. Behavioral guarantee: `finalizeSteeringIfNeeded` and `drainQueuedFollowUp` failures are logged best-effort and `process.exit` always runs.
+
+**Note:** this task has no practical unit test (module runs `main()` on import and the guarded code is inside a child-process event chain). It is covered by Task 4's integration tests + the fix is structurally simple. Red-green is not applicable; code-review verification is the gate (spec test-plan item 7).
+
+- [ ] **Step 1: Implement the guards**
+
+In `runner/job-runner.mjs`, replace the `.finally(() => { ... })` block:
+
+```js
+		.finally(() => {
+			// 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));
+		});
+```
+
+And add this helper next to `drainQueuedFollowUp` (appendDiagnostic itself throws on a deleted root — verified `appendLine` is not best-effort):
+
+```js
+/** @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 */
+	}
+}
+```
+
+- [ ] **Step 2: Sanity-check syntax + typecheck**
+
+Run: `node --check runner/job-runner.mjs && npm run typecheck`
+Expected: both clean.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add runner/job-runner.mjs
+git commit -m "fix: guard job-runner finalize chain so process.exit always runs (issue #33)"
+```
+
+---
+
+### Task 4: integration tests — kill detached runners in teardown
+
+**Files:**
+- Modify: `test/runner.integration.test.mjs`
+
+**Interfaces:**
+- Consumes: `launchRun(root, config, {runnerScript})` returns `{pid}` (all 7 call sites must capture it — 4 currently discard: the `needs_input`, `dash-prefixed`, `worker exits nonzero`, and `worker error` tests).
+- Produces: `killDetached(pid)` async helper; every test's `finally` kills the runner BEFORE `rmSync(root)`.
+
+- [ ] **Step 1: Add the helper (after the existing `sleep` definition)**
+
+```js
+/** Kill a detached runner before deleting its root so it can never orphan (issue #33). */
+async function killDetached(pid) {
+	if (!pid || pid <= 0) return;
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {
+		return; // already exited
+	}
+	const deadline = Date.now() + 1000;
+	while (Date.now() < deadline) {
+		await sleep(50);
+		try {
+			process.kill(pid, 0);
+		} catch {
+			return; // exited
+		}
+	}
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch {
+		/* already gone */
+	}
+}
+```
+
+- [ ] **Step 2: Capture pids at the 4 discarding call sites**
+
+Change `launchRun(root, config, { runnerScript: RUNNER });` to `const { pid } = launchRun(root, config, { runnerScript: RUNNER });` in the `needs_input`, `dash-prefixed prompts`, `worker exits nonzero`, and `worker error` tests. The `auto-classifies`, `readPid`, and remaining tests already capture the pid — leave them (rename only if a shadow conflict with `pid` arises; use `runnerPid` as the variable name at ALL sites for uniformity).
+
+- [ ] **Step 3: Kill before rmSync in every finally**
+
+In each test's `finally`, add `await killDetached(runnerPid);` as the FIRST statement, before `rmSync(root, ...)`. Example (first test):
+
+```js
+	} finally {
+		delete process.env.FAKE_PI_MODE;
+		// ...
+		await killDetached(runnerPid);
+		rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+	}
+```
+
+- [ ] **Step 4: Run the integration suite and check for leftovers**
+
+Run: `npm test -- --test-name-pattern "runner" && (ps -ef | grep '[j]ob-runner.mjs' || echo "no leftover runners")`
+Expected: all runner tests PASS and `no leftover runners` prints.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/runner.integration.test.mjs
+git commit -m "test: kill detached job-runners in integration test teardown (issue #33)"
+```
+
+---
+
+### Task 5: full verify + field-repro regression check
+
+**Files:**
+- Create: none (verification only; fixups allowed if verification exposes issues)
+
+- [ ] **Step 1: Full gate**
+
+Run: `npm run verify`
+Expected: typecheck + tests + coverage thresholds + pack:dry all green. If coverage thresholds fail on new branches, extend the Task 1 tests (not the thresholds).
+
+- [ ] **Step 2: Field-repro regression check (the /sys read-only scenario from the issue)**
+
+Run:
+```bash
+node -e '
+import("/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-33-locks-acquirelock-spin/src/core/locks.mjs").then(({ withFileLockSync }) => {
+	const t0 = Date.now();
+	try {
+		withFileLockSync("/sys/bus/pi-agent-board-repro.lock", () => {});
+		console.log("UNEXPECTED: acquired");
+	} catch (err) {
+		console.log("OK: threw in", Date.now() - t0, "ms:", err.message);
+	}
+});'
+```
+Expected: `OK: threw in < 1000 ms: file lock unavailable: /sys/bus/... (lock path unusable (EROFS))` — the pre-fix behavior was an infinite spin.
+
+- [ ] **Step 3: No zombies after the suite**
+
+Run: `ps -ef | grep -E '[j]ob-runner|[p]ty-runner.*agentview' || echo clean`
+Expected: `clean` (or only the user's real agent-board runners under ~/.pi/agent/agent-board).
+
+- [ ] **Step 4: Commit any fixups (only if Steps 1-3 required changes)**
+
+```bash
+git add <changed files>
+git commit -m "fix: address verify findings for issue #33"
+```
+
+---
+
+## Self-Review
+
+- **Spec coverage:** D1/D3/D4/D5/D8 → Task 1; D4b (re-ensureDir self-heal) → Task 1 implementation + self-heal test; D2 (wait/steal contract) → Task 1 keeps existing tests unmodified; D6 → Task 2; D7 → Task 3; D9 → Task 4; spec test items 1-3 → Task 1 tests, item 4/4b → Task 1 contention/self-heal tests, item 5 → Task 1 Step 4, item 6 → Task 2, item 7 → Task 3 (CR gate, documented), item 8 → Task 4 Step 4. Acceptance items map to Task 5. No gaps.
+- **Placeholder scan:** all steps contain concrete code / commands / expected output. No TBDs.
+- **Type consistency:** `defaultLocksFs` name used in Task 1 tests + implementation; `LOCK_TIMEOUT` code asserted in Task 1 and produced by `lockError`; `lockedQueueOp` defined in Task 2 and used at all 5 sites; `killDetached` defined and used in Task 4; `runnerPid` naming uniform in Task 4.

package/docs/superpowers/plans/2026-08-27-pty-runner-test-flaky.md

@@ -0,0 +1,32 @@
+# Plan: fix pty-runner integration test flaky timeout (issue #34)
+
+## Goal
+
+Make `pty-runner creates host socket, broadcasts output, forwards input, finalizes` deterministic on CI by not depending on pre-connect socket output. No product code change.
+
+## Tasks
+
+1. **Edit test** — `test/pty-runner.integration.test.mjs`
+   - Replace `await waitFor(() => messages.find((m) => m.type === "output" && m.data.includes("fake pi ready")));`
+     with a screen-log read wait:
+     ```js
+     await waitFor(() => {
+       try {
+         return readFileSync(P.screenLogPath(root, "v1"), "utf8").includes("fake pi ready");
+       } catch {
+         return false;
+       }
+     });
+     ```
+   - Keep all socket-based assertions (echo:hello, resize, exit) unchanged.
+2. **Verify** — run the pty-runner integration test repeatedly:
+   - `node --test test/pty-runner.integration.test.mjs` × 6, expect 3/3 pass each run.
+   - Forced late-connect scenario (output before connect) passes.
+   - Full suite `npm test` — 313/313 pass.
+3. **Commit** — conventional commit: `fix: make pty-runner integration test timing-independent (issue #34)`
+4. **PR** — push `issue-34-pty-runner-test-flaky`, open PR against main, tag `zima:needs-review`, await CR, converge, merge.
+
+## Verification
+
+- Deterministic under the previously-failing timing (output emitted before client connects).
+- No regression: full test suite green.

package/docs/superpowers/specs/2026-08-27-locks-acquirelock-spin-design.md

@@ -0,0 +1,97 @@
+# Spec: 修复 locks.mjs acquireLock 无眠死循环（issue #33）
+
+> Draft 状态：待用户确认设计后进 worktree 实现（github-issue-driven 步 4 暂停点）。
+
+## 问题
+
+`src/core/locks.mjs` `acquireLock` 在锁持续不可得时（根目录被删 / 只读 / 锁状态损坏），30s 等待窗过期后退化为零睡眠忙等循环：100% 单核 CPU、事件循环冻死、定时器全灭、进程永远不退出。现网两个 job-runner 僵尸进程分别空转 10.5 天 / 4.4 天（#33 现场证据）。
+
+## 根因（两处叠加）
+
+```js
+while (true) {
+    try {
+        mkdirSync(lockPath);
+        writeFileSync(path.join(lockPath, "owner.json"), ...);
+        return;
+    } catch (err) {
+        // 缺陷 1：睡眠只在初始窗口内生效，窗口一过永不睡眠
+        if (!isLockStale(lockPath, staleMs) && Date.now() - started < Math.max(250, staleMs)) {
+            Atomics.wait(...20ms);
+            continue;
+        }
+        // 缺陷 2：releaseLock 静默吞错，循环无条件继续 → 无眠紧循环
+        releaseLock(lockPath);
+    }
+}
+```
+
+**触发机制（现场还原）**：teardown 的 `rmSync(root, {recursive})` 与 runner 收尾链在时间上系统性重叠（runner 快速收尾链 ~10-50ms 到达锁 vs 测试 waitFor 轮询 ~50ms + 断言后才 rmSync ~50-150ms）。目录树遍历删掉 `ensureDir` 刚验证过的父目录后，`mkdirSync` 从此永远 ENOENT（**ensureDir 只在循环外跑一次，循环内永不重建父目录**）→ 30s 窗口后零睡眠死循环。另两类等价失败：owner.json 写失败（半成品锁被误判 stale → 删了重建无限循环）、锁目录删不掉（rmSync 失败被吞）。
+
+## 设计决策
+
+### 决策表
+
+| # | 决策点 | 选择 | 理由 |
+|---|---|---|---|
+| D1 | 强夺失败后的行为 | **有界尝试后抛错**（`Error: lock timeout: <path>`） | 锁不可得属环境故障，忙等无意义；抛错让调用层决定降级 |
+| D2 | 强夺（窗口后偷锁）语义 | **保留**：窗口过期 → releaseLock → 立即重试一次 | 现有测试「fresh lock 等窗口后强夺」固化此语义，改动会破坏契约 |
+| D3 | 重试上限 | 等待窗内无限重试（带睡眠，窗口 = `max(250, staleMs)`，保留现有 floor）；窗口后**最多 2 次强夺**（含 owner.json 写失败路径），仍失败即抛 | 覆盖 rm 失败 / mkdir 仍失败 / 写失败三类；有界即无死循环 |
+| D4 | 睡眠策略 | 保留 `Atomics.wait(20ms)`；循环内任何 continue 前必有睡眠或已抛错 | 反证 D1 的失败模式，杜绝任何无眠路径 |
+| D4b | **循环内自愈**：每次 catch 后重跑 `ensureDir(dirname)`（ensureDir 自身失败计为一次失败尝试） | 现场最高频竞态（teardown rmSync 删掉父目录）从「等窗口后抛错」升级为「瞬时自愈、正常拿锁退出」；有界性不变 |
+| D5 | fs 注入 | 仿 `screen-log.mjs` `defaultScreenLogFs` 先例，加 `locksFs` 参数（默认 node:fs） | 现有测试无注入，注入后才能确定性复现「mkdir 永败」等场景 |
+| D6 | 队列层错误传播 | follow-up-queue.mjs 5 个入口 try/catch **catch-all**（含 fn 内 writeFollowUpQueue 的 fs 错误，非仅锁错误）→ `{ok:false, error}` | 保持 {ok} 返回值约定，service.mjs 无需改动；已确认 follow-up-queue.test.mjs 无 throw 断言，catch-all 安全 |
+| D7 | job-runner 兜底 | `.finally` 链里 `finalizeSteeringIfNeeded` + `drainQueuedFollowUp` 各自 try/catch | 锁层抛错永远不会阻止 `process.exit`——僵尸进程防线最后一道 |
+| D8 | 默认 staleMs | 不变（30s） | 现有测试与调用方依赖 |
+| D9 | 测试 harness 清理 | 全部 7 处 launchRun 都捕获 pid（现有 4 处丢弃，含出过僵尸的 dash 测试）→ finally 里 TERM → 短等待 → KILL → 再 rmSync(root) | 现场两个僵尸的直接源头是 teardown 只删目录不杀 detached runner；这层保证测试不再产出孤儿（launch.test.mjs 的 detached fake-pi 已确认自然退出，无需处理） |
+
+### 数据流（修复后）
+
+```
+claimNextFollowUp(root, viewId)
+  → withViewLockSync(root, viewId, "queue", fn)
+    → acquireLock: [wait loop w/ sleep] → 窗口过期 → steal attempt ×2 → 失败 → throw
+  → catch → { ok: false, error: "follow-up queue lock unavailable: ..." }
+  → job-runner drainQueuedFollowUp: claimNextFollowUp 返回 {ok:false} → 直接 return（不进 launch）
+  → .finally → process.exit 必达
+```
+
+### 组件契约
+
+- `withFileLockSync` / `withViewLockSync`：成功返回 fn 结果；**新行为**——锁超时抛 `Error`（message 含 lockPath 与耗时）。
+- follow-up-queue 5 个导出（enqueue/claim/complete/release/remove/clear）：任何锁失败 → `{ok:false, error}`，不再抛出。
+- service.mjs：零改动（已按 {ok} 消费）。
+- job-runner.mjs：收尾链不因锁失败挂起。
+
+### 降级行为
+
+- 锁失败时队列操作静默失败并写 diagnostics（job-runner 用 appendDiagnostic；service 层已有该模式），用户可感知但系统不挂。
+- 不引入锁重试队列、不引入跨进程 watchdog——超出本 issue 范围。
+
+## 非目标
+
+- 不改锁的 mkdir 实现（不换 flock/其他机制）
+- 不处理「锁持有者崩溃残留」之外的竞争语义
+- 不改 30s staleMs 默认值
+- 不引入异步锁
+
+## 测试计划（red-green）
+
+test/locks.test.mjs 现有 5 测试全绿；新增（全部带 `{ timeout: 5000 }` 防挂）：
+
+1. **mkdir 永败**（注入 fs）：`withFileLockSync(..., { staleMs: 50 })` 在 ~250ms 窗口（`max(250, staleMs)` floor）后抛错，不在 5s 内挂起。
+2. **写 owner.json 永败**（注入 fs）：mkdir 成功但 writeFileSync 抛 → 有界强夺后抛错。
+3. **rmSync 永败**（注入 fs）：窗口后强夺 rm 失败 → 抛错。
+4. **争用正常恢复**：注入 fs 模拟「前 N 次 mkdir EEXIST、之后成功」→ 等待窗内获取成功（保语义 1）。
+4b. **父目录被删后自愈**（D4b）：真实 fs，锁获取前删掉父目录 → ensureDir 在循环内重建 → 正常拿锁（验证现场最高频竞态透明自愈）。
+5. **窗口后强夺仍成功**：复用现有测试 4（不回归）。
+6. follow-up-queue 层：锁失败 → `{ok:false, error}`（用注入 fs 或真实坏路径）。
+7. job-runner 收尾：若可低成本导出/集成测试则覆盖「锁坏时 drainQueuedFollowUp 不挂起、process 退出」；否则以代码评审 + 手动验证为准。
+8. 集成测试 teardown：runner 被杀后进程表里不再残留 job-runner（现有集成测试全绿即可证明 kill 生效）。
+
+## 验收
+
+- `npm test`（或 `npm run verify`）全绿
+- 35s 复现脚本（/sys 只读路径）修复后应立即抛错而非空转
+- 跑完集成测试后 `ps` 无残留 job-runner
+- 代码评审通过后 PR + Zima CR

package/docs/superpowers/specs/2026-08-27-pty-runner-test-flaky-design.md

@@ -0,0 +1,35 @@
+# Issue #34 — CI flaky: pty-runner integration test times out waiting for pre-connect output
+
+## Root cause
+
+`test/pty-runner.integration.test.mjs` (test "pty-runner creates host socket, broadcasts output, forwards input, finalizes") waits for the boot banner `fake pi ready` **over the control socket**. But the socket only carries *live* output: `broadcast()` iterates `clients`, which is empty until a client connects. If the child emits `fake pi ready` before the test's socket connects (CI runners start the child fast), the output is broadcast to zero clients and lost — the 3s `waitFor` times out.
+
+History output is intentionally NOT replayed over the socket; the UI attach path replays it from the screen log file (`src/ui/pty-attach.ts` `replayScreenLog`). The test's assumption contradicts the protocol design.
+
+### Evidence
+
+- CI run 32554867604 (main, #32): `not ok 181 ... error: 'timed out waiting'` at `test/pty-runner.integration.test.mjs:65`, both Node 22 and Node 24.
+- PR branch run 32554619699 failed on a *different* test (`runner.integration.test.mjs:195`, auto-done idle), passed on rerun — separate timing-sensitive spot, out of scope.
+- Reproduced deterministically locally with a forced "output before connect" script: 3/3 timeouts. Same test passes 5/5 under normal timing.
+- Local runs after fix: 6/6 pass; late-connect scenario: 3/3 pass; full suite: 313/313 pass.
+
+## Fix design
+
+Only the test changes; no product code change (socket protocol behavior is by design).
+
+| Step | File | Change |
+|------|------|--------|
+| 1 | `test/pty-runner.integration.test.mjs` | Replace the socket wait for `fake pi ready` with a screen-log read wait (`P.screenLogPath(root, "v1")` contains `fake pi ready`) — mirrors UI attach replay semantics |
+
+Assertions that remain on the socket (post-connect realtime events, timing-safe):
+- `echo:hello` output (live broadcast + input forwarding)
+- resize → `readHost().cols === 100`
+- `exit` → `endedAt` set, state `exited`
+
+Screen-log assertions (file-based, timing-safe):
+- boot banner `fake pi ready` present (already asserted at test end via `assert.match`)
+
+## Non-goals
+
+- No change to `runner/pty-runner.mjs` socket protocol.
+- No change to `runner.integration.test.mjs` flaky spot (tracked separately if it recurs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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

@@ -228,8 +228,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));
 			});
 	});
@@ -283,6 +293,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) {

package/src/core/follow-up-queue.mjs

@@ -5,6 +5,24 @@ import { truncate } from "./heuristics.mjs";
 import { withViewLockSync } from "./locks.mjs";
 import * as P from "./paths.mjs";
 
+/**
+ * Run a queue mutation under the view lock, translating any failure (lock
+ * unavailable, fs errors inside the mutation) into {ok:false} so callers on
+ * the {ok} convention never see a throw (issue #33).
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {() => T} fn
+ * @returns {T | { ok: false, error: string }}
+ */
+function lockedQueueOp(root, viewId, fn) {
+	try {
+		return withViewLockSync(root, viewId, "queue", fn);
+	} catch (err) {
+		return { ok: false, error: `follow-up queue lock unavailable: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}
+
 /** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").FollowUpQueue} */
 export function emptyFollowUpQueue(viewId, now = Date.now()) {
 	return { version: 1, viewId, nextSeq: 1, updatedAt: now, items: [] };
@@ -41,7 +59,7 @@ export function summarizeFollowUpQueue(queue) {
 export function enqueueFollowUp(root, viewId, text, opts = {}) {
 	const clean = String(text || "").trim();
 	if (!clean) return { ok: false, error: "Empty follow-up" };
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const now = Date.now();
 		const item = {
@@ -70,7 +88,7 @@ export function enqueueFollowUp(root, viewId, text, opts = {}) {
 
 /** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
 export function claimNextFollowUp(root, viewId, opts = {}) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const item = queue.items.filter((i) => i.status === "queued").sort((a, b) => a.seq - b.seq)[0];
 		if (!item) return { ok: false, error: "No queued follow-up" };
@@ -114,7 +132,7 @@ export function releaseFollowUp(root, viewId, itemId) {
 
 /** @param {string} root @param {string} viewId */
 export function removeLastFollowUp(root, viewId) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const queued = queue.items.filter((i) => i.status === "queued").sort((a, b) => b.seq - a.seq);
 		const last = queued[0];
@@ -128,7 +146,7 @@ export function removeLastFollowUp(root, viewId) {
 
 /** @param {string} root @param {string} viewId */
 export function clearQueuedFollowUps(root, viewId) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		let cancelled = 0;
 		for (const item of queue.items) {
@@ -145,7 +163,7 @@ export function clearQueuedFollowUps(root, viewId) {
 
 /** @param {string} root @param {string} viewId @param {string} itemId @param {(item: import("./types.mjs").FollowUpItem) => void} mutate */
 function updateItem(root, viewId, itemId, mutate) {
-	return withViewLockSync(root, viewId, "queue", () => {
+	return lockedQueueOp(root, viewId, () => {
 		const queue = readFollowUpQueue(root, viewId);
 		const item = queue.items.find((i) => i.id === itemId);
 		if (!item) return { ok: false, error: "Unknown follow-up" };

package/src/core/locks.mjs

@@ -1,6 +1,14 @@
 /**
  * Tiny dependency-free synchronous file lock helpers for local agent-board artifacts.
  * Locks use atomic mkdir on a sibling .lock directory and are cleaned up in finally.
+ *
+ * Failure model (issue #33): acquisition failures are classified.
+ * - EEXIST (contention): wait in 20ms ticks until the stale window passes, then
+ *   force-steal (bounded to MAX_STEAL_ATTEMPTS). This preserves the original
+ *   wait/steal contract (see test/locks.test.mjs).
+ * - Anything else (deleted parent, read-only fs, permissions, disk full, ...):
+ *   MAX_ENV_ATTEMPTS quick retries — each retry re-runs ensureDir so a parent
+ *   deleted mid-acquisition self-heals — then throw LOCK_TIMEOUT. Never spin.
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
@@ -8,22 +16,33 @@ import { ensureDir } from "./atomic.mjs";
 import * as P from "./paths.mjs";
 
 const DEFAULT_STALE_MS = 30_000;
+/** Minimum contention window before a fresh lock can be force-stolen. */
+const MIN_WINDOW_MS = 250;
+const WAIT_TICK_MS = 20;
+/** Max stale-lock steal attempts before giving up. */
+const MAX_STEAL_ATTEMPTS = 2;
+/** Max quick retries for environmental failures before giving up. */
+const MAX_ENV_ATTEMPTS = 3;
+
+export const defaultLocksFs = Object.freeze({ existsSync, mkdirSync, readFileSync, rmSync, writeFileSync });
 
 /**
  * @template T
  * @param {string} lockPath
  * @param {() => T} fn
- * @param {{ staleMs?: number }} [opts]
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
  * @returns {T}
  */
 export function withFileLockSync(lockPath, fn, opts = {}) {
-	const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
-	acquireLock(lockPath, staleMs);
+	const fs = opts.fs ?? defaultLocksFs;
+	acquireLock(lockPath, opts.staleMs ?? DEFAULT_STALE_MS, fs);
+	let result;
 	try {
-		return fn();
+		result = fn();
 	} finally {
-		releaseLock(lockPath);
+		releaseLock(lockPath, fs);
 	}
+	return result;
 }
 
 /**
@@ -32,37 +51,74 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
  * @param {string} viewId
  * @param {string} name
  * @param {() => T} fn
- * @param {{ staleMs?: number }} [opts]
+ * @param {{ staleMs?: number, fs?: typeof defaultLocksFs }} [opts]
  * @returns {T}
  */
 export function withViewLockSync(root, viewId, name, fn, opts = {}) {
 	return withFileLockSync(P.viewLockPath(root, viewId, name), fn, opts);
 }
 
-/** @param {string} lockPath @param {number} staleMs */
-function acquireLock(lockPath, staleMs) {
-	ensureDir(path.dirname(lockPath));
-	const started = Date.now();
-	while (true) {
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function acquireLock(lockPath, staleMs, fs) {
+	const deadline = Date.now() + Math.max(MIN_WINDOW_MS, staleMs);
+	let steals = 0;
+	let envAttempts = 0;
+	for (;;) {
+		let created = false;
 		try {
-			mkdirSync(lockPath);
-			writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }), "utf8");
+			// Re-run every attempt: a parent deleted mid-acquisition self-heals here.
+			ensureDir(path.dirname(lockPath));
+			fs.mkdirSync(lockPath);
+			created = true;
+			fs.writeFileSync(
+				path.join(lockPath, "owner.json"),
+				JSON.stringify({ pid: process.pid, at: Date.now() }),
+				"utf8",
+			);
 			return;
 		} catch (err) {
-			if (!isLockStale(lockPath, staleMs) && Date.now() - started < Math.max(250, staleMs)) {
-				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+			if (err && err.code === "EEXIST") {
+				const expired = Date.now() >= deadline;
+				if (isLockStale(lockPath, staleMs, fs) || expired) {
+					if (steals >= MAX_STEAL_ATTEMPTS) {
+						throw lockError(lockPath, `stale lock could not be stolen after ${steals} attempts`);
+					}
+					steals += 1;
+					releaseLock(lockPath, fs);
+					continue;
+				}
+				sleep(WAIT_TICK_MS);
 				continue;
 			}
-			releaseLock(lockPath);
+			// Environmental failure: bounded quick retries, then fail fast.
+			if (created) releaseLock(lockPath, fs);
+			envAttempts += 1;
+			if (envAttempts >= MAX_ENV_ATTEMPTS) {
+				const reason = (err && (err.code || err.message)) || "unknown error";
+				throw lockError(lockPath, `lock path unusable (${reason})`);
+			}
+			sleep(WAIT_TICK_MS);
 		}
 	}
 }
 
-/** @param {string} lockPath @param {number} staleMs */
-function isLockStale(lockPath, staleMs) {
+/** @param {string} lockPath @param {string} reason */
+function lockError(lockPath, reason) {
+	const err = new Error(`file lock unavailable: ${lockPath} (${reason})`);
+	err.code = "LOCK_TIMEOUT";
+	return err;
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** @param {string} lockPath @param {number} staleMs @param {typeof defaultLocksFs} fs */
+function isLockStale(lockPath, staleMs, fs) {
 	try {
-		if (!existsSync(lockPath)) return false;
-		const raw = readFileSync(path.join(lockPath, "owner.json"), "utf8");
+		if (!fs.existsSync(lockPath)) return false;
+		const raw = fs.readFileSync(path.join(lockPath, "owner.json"), "utf8");
 		const owner = JSON.parse(raw);
 		return Date.now() - Number(owner.at ?? 0) > staleMs;
 	} catch {
@@ -70,10 +126,10 @@ function isLockStale(lockPath, staleMs) {
 	}
 }
 
-/** @param {string} lockPath */
-function releaseLock(lockPath) {
+/** @param {string} lockPath @param {typeof defaultLocksFs} fs */
+function releaseLock(lockPath, fs) {
 	try {
-		rmSync(lockPath, { recursive: true, force: true });
+		fs.rmSync(lockPath, { recursive: true, force: true });
 	} catch {
 		/* best effort */
 	}