@zhuxixi/pi-agent-board 0.5.2 → 0.6.0

package/docs/superpowers/plans/2026-09-05-issue-13-drainnextfollowup-pty-probe.md

@@ -0,0 +1,114 @@
+# Issue #13 Drain-Path PTY Probe Refresh — 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:** Stop `drainNextFollowUp` (reachable from the 700ms reconcile poll) from forcing a real `pty.spawn` probe on every cycle; switch it to cached-probe semantics and lock that in with a red-green test.
+
+**Architecture:** One-line production change (`ptySupport({ refresh: true })` → `ptySupport()` in `drainNextFollowUp`) + one new test in `test/service.test.mjs` driving the public `reconcile()` API with an injected `ptySupport` spy, modeled on the existing "ensureHost probes PTY support with TTL cache" test and the "busy replies queue and drain when idle" row-state pattern.
+
+**Tech Stack:** Node built-in test runner; existing `createService` DI seams (`ptySupport`, `launch`).
+
+## Global Constraints
+
+- Production delta is exactly the one-line probe switch in `src/runtime/service.mjs` `drainNextFollowUp` (spec A4).
+- `dispatch` (L616) and `reply` (L649) keep `refresh: true` — explicit user actions.
+- No changes to `ptySpawnSupported` / `shouldProbePtySupport`.
+- Test command: `npm test` (= `node --test test/*.test.mjs`).
+
+**Execution mode:** inline (executing-plans) — single task, one-line production diff + one test.
+
+---
+
+### Task 1: Red-green test + one-line probe switch
+
+**Files:**
+- Modify: `src/runtime/service.mjs:496` (inside `drainNextFollowUp`)
+- Modify: `test/service.test.mjs` (append new test after "ensureHost probes PTY support with TTL cache, not forced refresh", ~L958)
+
+**Interfaces:**
+- Consumes: `createService` opts `{ ptySupport?: (opts?) => {ok, reason?}, launch?: typeof launchRun }`; public `svc.reconcile()`, `svc.queueFollowUp(viewId, text)`; helpers `freshRoot()`, `createView(root, {id, name, cwd})`, `readState`/`writeState`, `rmSync`.
+- Produces: nothing consumed by other tasks.
+
+- [ ] **Step 1: Write the failing test (red)**
+
+Append to `test/service.test.mjs` (after the "ensureHost probes PTY support with TTL cache, not forced refresh" test):
+
+```js
+test("reconcile auto-drain uses the cached PTY probe, never forced refresh", () => {
+	const root = freshRoot();
+	try {
+		createView(root, { id: "v1", name: "a", cwd: "/r" });
+		const st = readState(root, "v1");
+		st.semanticState = "idle";
+		st.processState = "exited";
+		writeState(root, st);
+		const probeCalls = [];
+		const svc = service(root, {
+			ptySupport: (opts = {}) => {
+				probeCalls.push(opts);
+				return { ok: false, reason: "test" };
+			},
+			launch: () => ({ pid: null, configPath: "/no/config.json" }),
+		});
+		const queued = svc.queueFollowUp("v1", "next step");
+		assert.equal(queued.ok, true);
+		const fixed = svc.reconcile();
+		assert.ok(fixed >= 1, "reconcile drained the queued follow-up");
+		assert.ok(probeCalls.length >= 1, "drain path probed ptySupport");
+		for (const opts of probeCalls) {
+			assert.notEqual(opts?.refresh, true, "reconcile→drain must not force ptySupport refresh");
+		}
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Run it, verify it fails against current production code**
+
+Run: `node --test test/service.test.mjs`
+Expected: FAIL — `reconcile→drain must not force ptySupport refresh` (production still passes `{refresh: true}`).
+
+- [ ] **Step 3: The one-line fix (green)**
+
+In `src/runtime/service.mjs` `drainNextFollowUp` (~L496), change:
+
+```js
+			const pty = ptySupport({ refresh: true });
+```
+
+to:
+
+```js
+			const pty = ptySupport();
+```
+
+(Only inside `drainNextFollowUp`. The `dispatch` and `reply` occurrences keep `{ refresh: true }`.)
+
+- [ ] **Step 4: Run the test file, verify pass**
+
+Run: `node --test test/service.test.mjs`
+Expected: PASS including the new test.
+
+- [ ] **Step 5: Full suite (A2/A3)**
+
+Run: `npm test`
+Expected: all green.
+
+- [ ] **Step 6: Verify A4 — scope**
+
+Run: `git diff main -- src/ test/`
+Expected: exactly one line changed in `src/runtime/service.mjs`, one test appended in `test/service.test.mjs`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/runtime/service.mjs test/service.test.mjs
+git commit -m "perf: use cached PTY probe on the reconcile drain path (issue #13)"
+```
+
+## Self-Review
+
+- Spec coverage: A1 (Steps 1-2 red, 3-4 green), A2/A3 (Step 5), A4 (Step 6). Covered.
+- Placeholder scan: exact code shown for both edits.
+- Type consistency: spy signature matches `createService` opts type; `launch` fake matches the pattern used by the existing "busy replies queue and drain when idle" test.

package/docs/superpowers/plans/2026-09-05-issue-38-windows-wezterm-ime-cursor.md

@@ -0,0 +1,73 @@
+# Issue #38 Windows WezTerm IME Docs — 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:** Document that Windows WezTerm attach sessions need a visible hardware cursor (`PI_HARDWARE_CURSOR=1` / `"showHardwareCursor": true`) for IME candidate tracking.
+
+**Architecture:** One new Troubleshooting subsection in README.md, placed after "### Attach is slow or keeps reconnecting".
+
+**Tech Stack:** Markdown only.
+
+## Global Constraints
+
+- Docs-only: README.md is the only non-process file touched (spec A2).
+- Both fixes documented with scope guidance; cosmetic trade-off stated.
+- No upstream comment on earendil-works/pi#5200 (owner's voice).
+
+**Execution mode:** inline (executing-plans).
+
+---
+
+### Task 1: Add the Troubleshooting subsection
+
+**Files:**
+- Modify: `README.md` (Troubleshooting section, after the "### Attach is slow or keeps reconnecting" block)
+
+- [ ] **Step 1: Insert the subsection**
+
+Insert after the "### Attach is slow or keeps reconnecting" paragraph, before "### Start & attach falls back to background":
+
+````markdown
+### IME candidate window is stuck at the window edge (Windows WezTerm)
+
+On Windows WezTerm with a WSL2 backend, the IME candidate window may stay
+pinned to the right edge instead of following the text cursor in an attached
+session. Windows WezTerm only tracks the IME candidate position from the
+visible hardware cursor, and Pi hides the hardware cursor by default — the
+block cursor you see in the editor is drawn content, not the hardware cursor.
+Linux terminals are not affected.
+
+Make the hardware cursor visible, either way:
+
+```bash
+export PI_HARDWARE_CURSOR=1    # machine-local, e.g. ~/.zshrc.local
+```
+
+or set `"showHardwareCursor": true` in Pi's `settings.json` (syncs across
+machines if the config is version-controlled; harmless on Linux).
+
+Trade-off: the real terminal cursor becomes visible inside the TUI. This is
+cosmetic only.
+````
+
+- [ ] **Step 2: Verify A1 (content presence)**
+
+Run: `grep -n "PI_HARDWARE_CURSOR=1\|showHardwareCursor\|IME candidate window is stuck" README.md`
+Expected: 3+ hits inside the Troubleshooting section.
+
+- [ ] **Step 3: Verify A2 (scope)**
+
+Run: `git diff main --stat`
+Expected: README.md + process docs under docs/superpowers/ only.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: Windows WezTerm IME needs a visible hardware cursor (issue #38)"
+```
+
+## Self-Review
+
+- Spec coverage: A1 (Step 2), A2 (Step 3). Covered.
+- Placeholder scan: full markdown shown.

package/docs/superpowers/plans/2026-09-05-issue-39-truncate-codepoint-boundary.md

@@ -0,0 +1,143 @@
+# Issue #39 Truncate Surrogate-Safe Cut — 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 `truncate()` in `src/core/heuristics.mjs` never split a surrogate pair (cut-point back-off within the UTF-16 unit budget) and never emit lone surrogates, eliminating the U+FFFD → width-mismatch → wrap → stacked-frames chain at its repo-side root.
+
+**Architecture:** Pure-function change inside `truncate` only: check whether the unit before the cut point is a high surrogate whose low surrogate is being dropped; if so, back the cut off by one unit. Strip any lone surrogates from the returned string on both paths via a small private regex helper.
+
+**Tech Stack:** Node built-in test runner; no new dependencies.
+
+## Global Constraints
+
+- Keep the UTF-16 unit budget semantics of `n` (spec Decision 1) — do NOT switch to code-point counting.
+- Only `src/core/heuristics.mjs` (truncate + private helper) and `test/heuristics.test.mjs` change (spec A5).
+- Existing tests must pass unmodified (spec A3).
+- Test command: `npm test`.
+
+**Execution mode:** inline (executing-plans).
+
+---
+
+### Task 1: Red tests at the surrogate boundaries
+
+**Files:**
+- Modify: `test/heuristics.test.mjs` (extend the existing "truncate adds ellipsis" test block or add a new test after it)
+
+**Interfaces:**
+- Consumes: `truncate(s, n)` exported from `src/core/heuristics.mjs`.
+- Produces: nothing consumed by other tasks.
+
+- [ ] **Step 1: Write the failing tests (red)**
+
+Replace the existing block:
+
+```js
+test("truncate adds ellipsis", () => {
+	assert.equal(truncate("hello", 10), "hello");
+	assert.equal(truncate("hello world", 5), "hell…");
+});
+```
+
+with:
+
+```js
+test("truncate adds ellipsis", () => {
+	assert.equal(truncate("hello", 10), "hello");
+	assert.equal(truncate("hello world", 5), "hell…");
+	assert.equal(truncate("一二三四五六", 5), "一二三四…");
+});
+
+test("truncate never splits a surrogate pair", () => {
+	// Cut point lands between the high and low surrogate of 👍: back off.
+	assert.equal(truncate("a👍b", 3), "a…");
+	// Long string whose 80-unit cut lands inside the emoji (issue #39 repro shape).
+	const s = "x".repeat(59) + "完成 — LGTM " + "👍" + "y".repeat(10);
+	const out = truncate(s, 80);
+	assert.ok(!/[\uD800-\uDBFF]$/.test(out.replace(/…$/, "")), "no trailing lone high surrogate before ellipsis");
+	// The pair survives whole when it fits the budget.
+	assert.equal(truncate("👍", 2), "👍");
+	assert.equal(truncate("a👍", 3), "a👍");
+});
+
+test("truncate strips lone surrogates from input", () => {
+	assert.equal(truncate("ab\ud83d", 10), "ab"); // lone high surrogate, short path
+	assert.equal(truncate("ab\ud83dcd", 4), "abc…"); // lone high surrogate, truncated path
+	assert.equal(truncate("\udc4dab", 10), "ab"); // lone low surrogate, short path
+});
+```
+
+Note on `"ab\ud83dcd"` with n=4: units are a,b,\ud83d,c,d (length 5 > 4) → cut end=3 → slice = "ab\ud83d" → the high surrogate is last-but-0 with no following unit in the *kept* slice; input's `\ud83d` is followed by `c` (not a low surrogate), so it is a lone surrogate in the input and must be stripped → expected "ab…". If the implementation instead computes end=3, sees charCodeAt(2) is a high surrogate and charCodeAt(3)="c" is not a low surrogate, no pair back-off applies (no pair to preserve) — the strip helper removes it → "ab…". Both reasonings converge; assert the observable "ab…".
+
+- [ ] **Step 2: Run, verify red**
+
+Run: `node --test test/heuristics.test.mjs`
+Expected: the two new tests FAIL (current implementation splits pairs / keeps lone surrogates), "truncate adds ellipsis" still passes.
+
+### Task 2: Implement the surrogate-safe truncate
+
+**Files:**
+- Modify: `src/core/heuristics.mjs` (replace `truncate`)
+
+- [ ] **Step 3: New implementation**
+
+Replace the existing `truncate` function with:
+
+```js
+const LONE_HIGH_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g;
+const LONE_LOW_SURROGATE_RE = /(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+/** @param {string} s */
+function stripLoneSurrogates(s) {
+	if (!s) return s;
+	return s.replace(LONE_HIGH_SURROGATE_RE, "").replace(LONE_LOW_SURROGATE_RE, "");
+}
+
+/**
+ * Truncate to `n` chars with an ellipsis (counts characters, not display width).
+ * The budget `n` is in UTF-16 units. The cut never splits a surrogate pair
+ * (backs off one unit when it would), and lone surrogates in the input are
+ * stripped from the result — a lone surrogate renders as U+FFFD, whose
+ * terminal width can disagree with the computed width and misalign rows.
+ * @param {string} s
+ * @param {number} n
+ * @returns {string}
+ */
+export function truncate(s, n) {
+	const str = String(s ?? "");
+	if (str.length <= n) return stripLoneSurrogates(str);
+	let end = Math.max(0, n - 1);
+	const lastUnit = str.charCodeAt(end - 1);
+	const nextUnit = str.charCodeAt(end);
+	if (lastUnit >= 0xd800 && lastUnit <= 0xdbff && nextUnit >= 0xdc00 && nextUnit <= 0xdfff) end -= 1;
+	return `${stripLoneSurrogates(str.slice(0, end))}…`;
+}
+```
+
+- [ ] **Step 4: Run the file, verify green**
+
+Run: `node --test test/heuristics.test.mjs`
+Expected: all pass, including the two new tests and the unchanged originals.
+
+- [ ] **Step 5: Full suite (A4)**
+
+Run: `npm test`
+Expected: all green.
+
+- [ ] **Step 6: Verify A5 scope**
+
+Run: `git diff main -- src/ test/`
+Expected: only `src/core/heuristics.mjs` and `test/heuristics.test.mjs`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/core/heuristics.mjs test/heuristics.test.mjs
+git commit -m "fix: truncate never splits surrogate pairs or emits lone surrogates (issue #39)"
+```
+
+## Self-Review
+
+- Spec coverage: A1 (Task 1 red + Task 2), A2 (lone-surrogate tests), A3 (unchanged originals + CJK case), A4 (Step 5), A5 (Step 6). Covered.
+- Placeholder scan: full code shown.
+- Type consistency: `stripLoneSurrogates` string→string; `charCodeAt` unit checks match the surrogate ranges used in the regexes.

package/docs/superpowers/plans/2026-09-05-issue-61-mention-fallback-guards.md

@@ -0,0 +1,226 @@
+# Issue #61 Mention Fallback Guards — 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:** Stop the Rule 6 bare `#N` mention fallback from lifting placeholder numbers: left-boundary guard, inline-code-span exclusion, PR-context kind-aware skip, plus a documented providers.json example for internal-platform CLIs.
+
+**Architecture:** Three guards inside `mentionFallback`/`MENTION_RE` (pure regex logic), one README example. Tests go through the public `extractCodeRefs` seam like all existing mention tests.
+
+**Tech Stack:** Node built-in test runner; no new dependencies.
+
+## Global Constraints
+
+- Issue-only fallback stays (no PR mention candidate fabrication) — spec non-goals.
+- Existing mention tests unchanged (spec A5).
+- Only `src/core/code-refs.mjs`, `README.md` (Evidence section), `test/code-refs-extract.test.mjs` change (spec A7).
+- Test command: `npm test`.
+
+**Execution mode:** inline (executing-plans).
+
+---
+
+### Task 1: Red tests for the three guards + composite repro
+
+**Files:**
+- Modify: `test/code-refs-extract.test.mjs` (after the existing "mention fallback yields no winner" test, ~L283)
+
+- [ ] **Step 1: Add failing tests**
+
+```js
+test("mention fallback ignores ##N heading forms and word-prefixed #N (issue #61)", () => {
+	const result = extractCodeRefs(
+		{ commands: [], assistantTexts: ["##1378", "##1378", "##1378", "a#1378", "b#99"], worktreePath: null, branch: null, repoUrl: null, host: null },
+		github()
+	);
+	assert.equal(result.issue, null);
+	assert.equal(result.pr, null);
+});
+
+test("mention fallback ignores #N inside inline code spans (issue #61)", () => {
+	const result = extractCodeRefs(
+		{ commands: [], assistantTexts: ["`monitor pr #1378`", "`#1378` x3", "see `#1378`"], worktreePath: null, branch: null, repoUrl: null, host: null },
+		github()
+	);
+	assert.equal(result.issue, null);
+});
+
+test("mention fallback does not count pr-context #N toward issue candidates (issue #61)", () => {
+	const result = extractCodeRefs(
+		{ commands: [], assistantTexts: ["monitor pr #1378", "monitor pr #1378", "monitor pr #1378", "monitor pr #1378", "monitor pr #1378"], worktreePath: null, branch: null, repoUrl: null, host: null },
+		github()
+	);
+	assert.equal(result.issue, null);
+});
+
+test("issue #61 repro shape: guarded placeholder loses, real issue prose wins", () => {
+	const result = extractCodeRefs(
+		{
+			commands: [],
+			assistantTexts: [
+				"设置 IID=\"#1378\" 会让 \"#$IID\" 展开成 \"##1378\" → 404",   // ##1378 heading-guard form
+				"`monitor pr #1378` 文档示例",                                   // code-span form
+				"monitor pr #1378 用户独立调用",                                 // pr-context form
+				"正在处理 issue #18", "issue #18 的修复", "更新 #18 状态",       // real issue prose ×3
+			],
+			worktreePath: null, branch: null, repoUrl: null, host: null,
+		},
+		github()
+	);
+	assert.equal(result.issue.number, 18);
+	assert.equal(result.issue.strength, "mention");
+});
+```
+
+Note on the heading test: `##1378` — with the guard, the second `#` is preceded by `#` → no match; the first `#` is followed by `#` not digits → no match. `a#1378`/`b#99`: preceded by word char → no match. Expected result with OLD code: `#1378` counts 3× (from the `##1378` lines' second hash) + more → a winner exists → test fails (red).
+
+- [ ] **Step 2: Run, verify red**
+
+Run: `node --test test/code-refs-extract.test.mjs`
+Expected: the new tests fail against current code; existing tests green.
+
+### Task 2: Implement the guards
+
+**Files:**
+- Modify: `src/core/code-refs.mjs` (MENTION_RE L549; mentionFallback L767)
+
+- [ ] **Step 3: Code changes**
+
+Replace:
+
+```js
+/** Bare `#N` mentions. */
+const MENTION_RE = /#(\d{1,7})/g;
+```
+
+with:
+
+```js
+/**
+ * Bare `#N` mentions. The lookbehind rejects a preceding `#` (markdown
+ * headings, `##N` typos) or word character (`a#1`) — those are not issue
+ * references (issue #61).
+ */
+const MENTION_RE = /(?<![#\w])#(\d{1,7})/g;
+/** Inline code span (single-line) — excluded from mention counting. */
+const INLINE_CODE_SPAN_RE = /`[^`\n]*`/g;
+/** Explicit PR-context tokens immediately before a `#N` match. */
+const PR_CONTEXT_RE = /(?:^|\W)(?:pr|pull|mr|merge)s?(?:\W|$)/i;
+```
+
+In `mentionFallback`, replace the counting loop:
+
+```js
+	for (let i = start; i < assistantTexts.length; i++) {
+		const text = assistantTexts[i];
+		if (typeof text !== "string") continue;
+		for (const m of text.matchAll(MENTION_RE)) {
+			const n = Number(m[1]);
+			counts.set(n, (counts.get(n) ?? 0) + 1);
+			lastIndex.set(n, baseIndex + i);
+		}
+	}
+```
+
+with:
+
+```js
+	for (let i = start; i < assistantTexts.length; i++) {
+		const text = assistantTexts[i];
+		if (typeof text !== "string") continue;
+		// Doc examples inside inline code spans are not real references; strip
+		// them before counting (issue #61).
+		const stripped = text.replace(INLINE_CODE_SPAN_RE, " ");
+		for (const m of stripped.matchAll(MENTION_RE)) {
+			// `monitor pr #N` is explicitly PR context: do not count it toward
+			// the issue fallback (issue #61).
+			const before = stripped.slice(Math.max(0, m.index - 16), m.index);
+			if (PR_CONTEXT_RE.test(before)) continue;
+			const n = Number(m[1]);
+			counts.set(n, (counts.get(n) ?? 0) + 1);
+			lastIndex.set(n, baseIndex + i);
+		}
+	}
+```
+
+- [ ] **Step 4: Run test file, verify green**
+
+Run: `node --test test/code-refs-extract.test.mjs`
+Expected: all pass (new + existing).
+
+- [ ] **Step 5: Full suite (A5)**
+
+Run: `npm test`
+Expected: all green.
+
+### Task 3: README providers.json example (G1/A6)
+
+**Files:**
+- Modify: `README.md` (Evidence and Code References section)
+- Modify: `test/code-refs-extract.test.mjs` (one JSON-validity test)
+
+- [ ] **Step 6: Append after the section's first paragraph**
+
+```markdown
+For internal code platforms (non-github/gitlab hosts) or custom CLIs, add a
+per-store `providers.json` so claim/action rules exist and sessions stop
+depending on the low-confidence mention fallback. Example — an internal CLI
+(`acli`) with claim-strength issue rules:
+
+```json
+{
+  "providers": [
+    {
+      "name": "acode",
+      "hosts": ["acode.internal.example.com"],
+      "rules": [
+        { "pattern": "acli\\s+issue\\s+update\\s+#?(\\d+)(?=[\\s\\S]*--assignee)", "kind": "issue", "strength": "claim" },
+        { "pattern": "acli\\s+issue\\s+(?:note|comment|close)\\s+#?(\\d+)", "kind": "issue", "strength": "action" },
+        { "pattern": "acli\\s+issue\\s+(?:show|view)\\s+#?(\\d+)", "kind": "issue", "strength": "view" }
+      ]
+    }
+  ]
+}
+```
+
+`hosts` matches the repo's remote host; rules follow the same
+`pattern`/`kind`/`strength` shape as the built-in `gh`/`glab` tables
+(`strength`: `claim` > `action` > `view`), and `#N` in the matched text
+captures the number. Validation errors from a broken file are surfaced in the
+diagnostics panel and never break extraction — the file is simply ignored.
+```
+
+- [ ] **Step 7: JSON-validity test**
+
+```js
+test("README providers.json example parses and validates (issue #61)", async () => {
+	const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8");
+	const fence = readme.match(/```json\n(\{[\s\S]*?providers[\s\S]*?\})\n```/);
+	assert.ok(fence, "README contains a json providers example");
+	const parsed = JSON.parse(fence[1]);
+	const { provider, errors } = validateProvider(parsed.providers[0]);
+	assert.deepEqual(errors, []);
+	assert.equal(provider.name, "acode");
+	assert.equal(provider.rules.length, 3);
+});
+```
+
+Add `validateProvider` to the import from `../src/core/code-refs.mjs` and
+`readFileSync` to the node:fs import if not already present.
+
+- [ ] **Step 8: Full suite + scope (A5/A7)**
+
+Run: `npm test` and `git diff main -- src/ README.md test/ --stat`
+Expected: all green; scope = code-refs.mjs, README.md, code-refs-extract.test.mjs.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/core/code-refs.mjs README.md test/code-refs-extract.test.mjs
+git commit -m "fix: guard mention fallback against placeholders, code spans, and pr-context (issue #61)"
+```
+
+## Self-Review
+
+- Spec coverage: A1/A2/A3 (Task 1 red + Task 2), A4 (composite test), A5 (Step 5), A6 (Task 3), A7 (Step 8). Covered.
+- Placeholder scan: full code shown.
+- Type consistency: regexes module-level constants; matchAll index usage valid post-strip (indices refer to `stripped`, used only for the window check).

package/docs/superpowers/plans/2026-09-05-issue-63-flaky-manual-completion.md

@@ -0,0 +1,87 @@
+# Issue #63 Flaky Manual-Completion Assert — 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:** Stop the runner.integration "manual completion" test from racing `markCompleted` against the status.json→state.json persist window (test-only fix).
+
+**Architecture:** Replace the one-shot `assert.deepEqual(createService({root}).markCompleted("view_1"), {ok:true})` with a `waitFor` poll of `markCompleted` until `{ok:true}`, then assert the exact shape. Durability asserts after runner exit stay unchanged.
+
+**Tech Stack:** Node built-in test runner (`node --test`), existing `waitFor(fn, timeoutMs = 15000, intervalMs = 50)` helper in the test file.
+
+## Global Constraints
+
+- Test-only: modify `test/runner.integration.test.mjs` and nothing else (spec A4).
+- No production code change under `runner/` or `src/` (spec Non-goals).
+- Test command: `npm test` (= `node --test test/*.test.mjs`).
+- Commit style: conventional commits.
+
+**Execution mode:** inline (executing-plans) — single task, 3-line diff; the heavy part is the 10-run verification loop which stays in the controlling session.
+
+---
+
+### Task 1: Poll markCompleted to success in runner.integration test
+
+**Files:**
+- Modify: `test/runner.integration.test.mjs` (~L357-364, test "runner does not clobber a manual completion made during post-exit model passes")
+
+**Interfaces:**
+- Consumes: `waitFor(fn, timeoutMs = 15000, intervalMs = 50)` (defined at top of same file), `createService({ root }).markCompleted(viewId)` → `{ ok: boolean, error?: string }`.
+- Produces: nothing consumed by other tasks.
+
+- [ ] **Step 1: Replace the one-shot assertion with a poll**
+
+Replace:
+
+```js
+		// User marks the row done manually while the model passes are in flight.
+		const { createService } = await import("../src/runtime/service.mjs");
+		assert.deepEqual(createService({ root }).markCompleted("view_1"), { ok: true });
+```
+
+with:
+
+```js
+		// User marks the row done manually while the model passes are in flight.
+		// persist() writes status.json before state.json, so markCompleted can
+		// transiently reject ("active run") after endedAt is already visible.
+		// Poll it to success, then assert the exact shape; the race window is
+		// millisecond-scale and 15s default timeout is ample.
+		const { createService } = await import("../src/runtime/service.mjs");
+		const svc = createService({ root });
+		let manual = null;
+		await waitFor(() => {
+			manual = svc.markCompleted("view_1");
+			return manual.ok ? manual : null;
+		});
+		assert.deepEqual(manual, { ok: true });
+```
+
+Note: if `waitFor` times out it returns `null` and leaves `manual` falsy-or-`{ok:false}`; the trailing `assert.deepEqual` then fails — timeout is still a test failure, not a silent pass.
+
+- [ ] **Step 2: Run the single test file, expect pass**
+
+Run: `npm test` (full suite; there is no per-file filter in `node --test` glob mode — use `node --test test/runner.integration.test.mjs` for the quick check)
+Expected: PASS, no other test affected.
+
+- [ ] **Step 3: Verify A3 — 10 consecutive full `npm test` runs**
+
+Run: `for i in $(seq 1 10); do npm test > /tmp/issue63-run-$i.log 2>&1 || { echo "RUN $i FAILED"; break; }; echo "run $i ok"; done`
+Expected: `run 1 ok` … `run 10 ok`, zero failures (spec A3).
+
+- [ ] **Step 4: Verify A4 — only the test file changed**
+
+Run: `git diff main --stat`
+Expected: exactly one file: `test/runner.integration.test.mjs`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/runner.integration.test.mjs
+git commit -m "test: poll markCompleted to success instead of racing the persist window (issue #63)"
+```
+
+## Self-Review
+
+- Spec coverage: A1 (Step 1 diff shape), A2 (Step 2 + unchanged durability asserts), A3 (Step 3), A4 (Step 4). Covered.
+- Placeholder scan: no TBD/TODO; exact code shown.
+- Type consistency: `manual` is `{ok:boolean,error?:string}`; `waitFor` returns truthy-on-success, `null` on timeout. Consistent.