@zhuxixi/pi-agent-board 0.4.2 → 0.5.0

package/README.md

@@ -82,6 +82,7 @@ Useful environment variables:
 | `AGENT_BOARD_AUTO_STATE=off` | Disable automatic terminal-state moves. |
 | `AGENT_BOARD_AUTO_STATE_MODEL=<model>` | Model for classifying finished turns. Defaults to `gpt-4o`; use `off` for heuristic-only. |
 | `AGENT_BOARD_AUTO_STATE_NO_DONE` | Disables automatic `completed` classification (default: enabled). Set to `0`/`false`/`off`/`no` to restore auto-done. |
+| `AGENT_BOARD_CODE_REFS=off` | Disable issue/PR badge extraction from session evidence. |
 | `AGENT_BOARD_SUMMARY_MODEL=<model>` | Model for short row summaries. Defaults to `gpt-4o`; use `off` to disable. |
 | `AGENT_BOARD_TITLE_MODEL=<model>` | Model for generated session titles. Defaults to `openai-codex/gpt-5.5`; use `off` to disable. |
 | `AGENT_BOARD_TITLE_THINKING_LEVEL=<level>` | Thinking level for title generation. Defaults to `low`; use `off` to omit it. |
@@ -101,6 +102,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 +112,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.