@huseynsnmz/pi-board 0.15.3 → 0.17.0

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

@@ -1,614 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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.