taskplane 0.30.1 → 0.30.3

package/README.md

@@ -61,6 +61,26 @@ IMPORTANT: If you just installed pi, make sure you've configured at least one mo
 pi install npm:taskplane
 ```
 
+As of pi `0.75.0`, this installs Taskplane into pi's private extension directory (`~/.pi/agent/npm/node_modules/`) rather than the system npm-global root. To make the `taskplane` CLI available on your shell PATH, add pi's bin dir once:
+
+```bash
+# bash / zsh
+echo 'export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
+```
+
+```powershell
+# PowerShell
+[Environment]::SetEnvironmentVariable(
+  "PATH",
+  "$HOME\.pi\agent\npm\node_modules\.bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"),
+  "User"
+)
+```
+
+With Pi's bin dir on PATH, `pi update` keeps Taskplane current automatically — there's no second update command to remember.
+
+> **Note for users who previously ran `npm install -g taskplane`:** That puts a second copy of Taskplane in your system npm-global, separate from pi's private copy. The two copies drift independently (`pi update` only refreshes the pi-private one), and your shell will resolve `taskplane` to whichever is earlier on PATH. Run `taskplane doctor` — it now detects this duplication and prints a remediation. The fix is `npm uninstall -g taskplane` plus the PATH change above.
+
 ### Option B: Single Project-Local Install
 
 ```bash
@@ -68,6 +88,8 @@ cd my-project
 pi install -l npm:taskplane
 ```
 
+Project-local installs land in `.pi/npm/node_modules/`. Either invoke via `npx taskplane <cmd>`, run the binary directly at `.pi/npm/node_modules/.bin/taskplane`, or add that dir to PATH (project-scoped — e.g. via a `.envrc` if you use direnv).
+
 ## Quickstart
 
 ### 1. Initialize a project (to scaffold settings)

package/bin/taskplane.mjs

@@ -2789,6 +2789,53 @@ function cmdDoctor() {
 		`  ${OK} taskplane package installed ${c.dim}(v${pkgVersion}, ${installType})${c.reset}`,
 	);
 
+	// Duplication check: when both the Pi-private and the npm-global copies
+	// exist with different versions, `pi update` only refreshes the Pi-private
+	// one and the system-wide CLI silently drifts behind. Surface this clearly
+	// so operators don't run a stale CLI thinking `pi update` covered it.
+	// Background: Pi 0.75.0 (2026-05-17) moved user-scoped pi packages from
+	// npm's global root to `~/.pi/agent/npm/` to avoid system-Node permission
+	// errors. Users who installed via `npm install -g taskplane` before that
+	// landed (or who installed via both paths) end up with two on-disk copies.
+	let duplicationDetected = false;
+	const duplication = detectDuplicateTaskplaneInstall();
+	if (duplication) {
+		duplicationDetected = true;
+		console.log();
+		console.log(`  ${WARN} taskplane is installed in TWO locations with different versions:`);
+		for (const loc of duplication.locations) {
+			console.log(
+				`     ${c.dim}${loc.label}:${c.reset} v${loc.version}  ${c.dim}(${loc.path})${c.reset}`,
+			);
+		}
+		console.log(
+			`     ${c.dim}→ ${c.reset}\`pi update\`${c.dim} only refreshes the Pi-private copy.${c.reset}`,
+		);
+		console.log(
+			`     ${c.dim}→ Recommended fix: drop the npm-global copy and put Pi's bin dir on PATH:${c.reset}`,
+		);
+		console.log(`     ${c.cyan}    npm uninstall -g taskplane${c.reset}`);
+		// Platform-aware PATH guidance: PowerShell on Windows, bash/zsh elsewhere.
+		// Linux & macOS users running PowerShell can still copy the bash form;
+		// Windows users running Git Bash can still copy the PowerShell form. The
+		// platform check picks the line most likely to match a fresh shell on
+		// the host OS so the inline copy/paste path is one-line on the common
+		// case.
+		if (process.platform === "win32") {
+			console.log(
+				`     ${c.cyan}    $env:PATH = "$HOME\\.pi\\agent\\npm\\node_modules\\.bin;" + $env:PATH${c.reset}  ${c.dim}# PowerShell, add to $PROFILE${c.reset}`,
+			);
+			console.log(
+				`     ${c.dim}    or, for Git Bash:${c.reset} ${c.cyan}export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"${c.reset}  ${c.dim}# ~/.bashrc${c.reset}`,
+			);
+		} else {
+			console.log(
+				`     ${c.cyan}    export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"${c.reset}  ${c.dim}# add to ~/.bashrc / ~/.zshrc${c.reset}`,
+			);
+		}
+		issues++;
+	}
+
 	if (isWorkspaceMode) {
 		console.log();
 		if (wsResult.error) {
@@ -3315,9 +3362,21 @@ function cmdDoctor() {
 	if (issues === 0) {
 		console.log(`${OK} ${c.green}All checks passed!${c.reset}\n`);
 	} else {
-		console.log(
-			`${FAIL} ${issues} issue(s) found. Run ${c.cyan}taskplane init${c.reset} to fix config issues.\n`,
-		);
+		// Each check above prints its own inline remediation hint, so the
+		// summary points back to those rather than recommending a single
+		// generic fix. The previous summary always recommended
+		// `taskplane init`, which was misleading when the underlying issue
+		// was a duplicate install (whose remediation is
+		// `npm uninstall -g taskplane`, not init).
+		if (duplicationDetected) {
+			console.log(
+				`${FAIL} ${issues} issue(s) found. See remediation hints above (${c.cyan}npm uninstall -g taskplane${c.reset} for the duplicate install).\n`,
+			);
+		} else {
+			console.log(
+				`${FAIL} ${issues} issue(s) found. See remediation hints above; run ${c.cyan}taskplane init${c.reset} to fix config issues.\n`,
+			);
+		}
 		process.exit(1);
 	}
 }
@@ -3332,17 +3391,28 @@ function cmdVersion() {
 	console.log(`\ntaskplane ${c.bold}v${pkgVersion}${c.reset}`);
 	console.log(`  Package:  ${installType}`);
 
-	// Check for project config
+	// Check for project config. Only render the `version` / `installedAt`
+	// fields when they're actually present and non-empty — some marker files
+	// (e.g. taskplane's own source repo, where `.pi/taskplane.json` carries
+	// only migration history rather than init metadata) would otherwise
+	// produce the user-visible "vundefined, initialized unknown" placeholders.
 	const projectRoot = process.cwd();
 	const tpJson = path.join(projectRoot, ".pi", "taskplane.json");
 	if (fs.existsSync(tpJson)) {
 		try {
 			const info = JSON.parse(fs.readFileSync(tpJson, "utf-8"));
-			console.log(
-				`  Config:   .pi/taskplane.json (v${info.version}, initialized ${info.installedAt?.slice(0, 10) || "unknown"})`,
-			);
+			const parts = [];
+			if (typeof info.version === "string" && info.version.length > 0) {
+				parts.push(`v${info.version}`);
+			}
+			if (typeof info.installedAt === "string" && info.installedAt.length > 0) {
+				parts.push(`initialized ${info.installedAt.slice(0, 10)}`);
+			}
+			const suffix =
+				parts.length > 0 ? ` (${parts.join(", ")})` : ` ${c.dim}(metadata only)${c.reset}`;
+			console.log(`  Config:   .pi/taskplane.json${suffix}`);
 		} catch {
-			console.log(`  Config:   .pi/taskplane.json (unreadable)`);
+			console.log(`  Config:   .pi/taskplane.json ${c.dim}(unreadable)${c.reset}`);
 		}
 	} else {
 		console.log(`  Config:   ${c.dim}not initialized (run taskplane init)${c.reset}`);
@@ -3366,6 +3436,82 @@ function getPackageVersion() {
 	}
 }
 
+/**
+ * Detect a duplicate taskplane install: one copy at Pi's private extension
+ * directory (`~/.pi/agent/npm/node_modules/taskplane/`) and another at the
+ * system npm-global root, with DIFFERENT versions. Same-version installs
+ * are harmless and intentionally not flagged (they may drift later but
+ * aren't a problem in the present tense).
+ *
+ * Returns null when there's no detectable duplication, or an object
+ * describing the two locations + their versions when there is.
+ *
+ * Best-effort: silently returns null if `npm root -g` is unreachable or
+ * either package.json is unreadable, since the rest of `taskplane doctor`
+ * should never crash on a side check.
+ *
+ * Background: Pi 0.75.0 (2026-05-17) moved user-scoped pi packages from
+ * npm's global root to `~/.pi/agent/npm/` to avoid permission errors with
+ * system-managed Node installs (Pi changelog: "Fixed user-scoped npm pi
+ * packages to install under `~/.pi/agent/npm/` instead of npm's global
+ * package root"). Users who had previously run `npm install -g taskplane`
+ * (or who continue to do so per older docs) now have two on-disk copies
+ * that drift independently: `pi update` only refreshes the Pi-private one.
+ */
+function detectDuplicateTaskplaneInstall() {
+	const piPrivatePath = path.join(homedir(), ".pi", "agent", "npm", "node_modules", "taskplane");
+
+	let npmRootGlobal = null;
+	try {
+		// 5s timeout guards against the rare case where `npm` is on PATH but
+		// hangs (slow registry probe, misconfigured custom prefix, etc.).
+		// `taskplane doctor` is a diagnostic — it should never make the CLI
+		// itself feel hung. On timeout, execSync throws and we fall back to
+		// the catch branch, returning null and silently skipping the
+		// duplication check (best-effort by design).
+		npmRootGlobal = execSync("npm root -g", {
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+			timeout: 5000,
+		})
+			.toString()
+			.trim();
+	} catch {
+		return null;
+	}
+	if (!npmRootGlobal) return null;
+	const npmGlobalPath = path.join(npmRootGlobal, "taskplane");
+
+	// Skip if Pi-private and npm-global resolve to the same path on disk.
+	// This can happen on installs where Pi hasn't (yet) migrated to its
+	// private directory or where the two paths point at the same install.
+	if (path.resolve(piPrivatePath) === path.resolve(npmGlobalPath)) return null;
+
+	const candidates = [
+		{ path: piPrivatePath, label: "Pi-private" },
+		{ path: npmGlobalPath, label: "npm-global" },
+	];
+
+	const found = [];
+	for (const candidate of candidates) {
+		try {
+			const pkgJsonPath = path.join(candidate.path, "package.json");
+			if (!fs.existsSync(pkgJsonPath)) continue;
+			const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+			if (typeof pkg.version !== "string" || pkg.version.length === 0) continue;
+			found.push({ path: candidate.path, label: candidate.label, version: pkg.version });
+		} catch {
+			/* unreadable — skip this candidate */
+		}
+	}
+
+	// Need both copies to be a duplication. Same-version pair is not flagged.
+	if (found.length < 2) return null;
+	if (found[0].version === found[1].version) return null;
+
+	return { locations: found };
+}
+
 // ─── dashboard ──────────────────────────────────────────────────────────────
 
 function cmdDashboard(args) {

package/dashboard/public/app.js

@@ -243,6 +243,17 @@ let viewerMode = null;   // "conversation" | "status-md" | null
 let viewerTarget = null; // session name (conversation) or taskId (status-md)
 let lastBatchId = null;  // TP-178: track batchId for stale viewer detection (#487)
 
+// #507: Debounce the no-batch transition. A single missed poll happens
+// transiently during batch-state.json writes at batch startup, and was
+// causing the dashboard to flash the previous batch's history view before
+// switching to the new live batch. Require N consecutive no-batch polls
+// before clearing the viewer / showing history. With the server's 2s
+// POLL_INTERVAL, a threshold of 3 corresponds to ~6s of confirmed silence —
+// well past the typical batch-state.json write window (sub-second) while
+// still cleaning up promptly when a batch genuinely ends.
+let consecutiveNoBatchPolls = 0;
+const NO_BATCH_DEBOUNCE_THRESHOLD = 3;
+
 // ─── Repo Helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -1818,6 +1829,16 @@ function render(data) {
   $lastUpdate.textContent = new Date().toLocaleTimeString();
 
   if (!batch) {
+    // #507: A single missed poll during batch startup (batch-state.json being
+    // written) is not a real "batch disappeared" signal. Only act on no-batch
+    // after N consecutive polls confirm it, so we don't flash the history
+    // view between two live batches.
+    consecutiveNoBatchPolls += 1;
+    if (consecutiveNoBatchPolls < NO_BATCH_DEBOUNCE_THRESHOLD) {
+      // Hold the previous render in place. Still tick the timestamp so the
+      // user knows the SSE stream is alive.
+      return;
+    }
     // TP-178: Clear viewer when batch disappears (#487)
     if (lastBatchId && viewerMode) closeViewer();
     lastBatchId = null;
@@ -1830,6 +1851,9 @@ function render(data) {
     return;
   }
 
+  // Batch present — reset the no-batch debounce counter (#507).
+  consecutiveNoBatchPolls = 0;
+
   // TP-178: Detect batchId change — clear stale viewer state (#487)
   if (batch.batchId && lastBatchId && batch.batchId !== lastBatchId && viewerMode) {
     closeViewer();

package/dashboard/server.cjs

@@ -467,12 +467,26 @@ function loadRuntimeLaneSnapshots(batchId) {
 /**
  * Load Runtime V2 merge agent snapshots for the current batch.
  *
- * Reads all `merge-N.json` files from `.pi/runtime/{batchId}/lanes/`.
- * Returns a map of mergeNumber (string) → snapshot data.
+ * Reads all `merge-*.json` files from `.pi/runtime/{batchId}/lanes/`.
+ * Returns a map of unique key → snapshot data, where the key is a composite
+ * of waveIndex and mergeNumber.
+ *
+ * The composite key is essential because lane numbers (and therefore
+ * `mergeNumber`) repeat across waves — keying solely by `mergeNumber` caused
+ * wave N+1's snapshots to silently overwrite wave N's in the intermediate
+ * map, which is the root cause of #509 ('merge agent telemetry missing for
+ * some waves').
  *
  * Follows the same pattern as {@link loadRuntimeLaneSnapshots}.
  *
- * @since TP-164
+ * Filename accepted patterns (back-compat-tolerant):
+ *   merge-w{waveIndex}-{mergeNumber}.json  (current, post-#509)
+ *   merge-{mergeNumber}.json               (legacy, pre-#509)
+ *
+ * Both patterns embed waveIndex inside the snapshot JSON itself, so the key
+ * derivation works for either filename.
+ *
+ * @since TP-164 (composite key added in #509 remediation)
  */
 function loadRuntimeMergeSnapshots(batchId) {
   if (!batchId) return {};
@@ -484,7 +498,14 @@ function loadRuntimeMergeSnapshots(batchId) {
     for (const file of files) {
       try {
         const data = JSON.parse(fs.readFileSync(path.join(lanesDir, file), "utf-8"));
-        if (data.mergeNumber != null) snapshots[data.mergeNumber] = data;
+        if (data.mergeNumber == null) continue;
+        // Composite key keeps cross-wave snapshots from colliding in this map.
+        // Falls back to mergeNumber-only for legacy snapshots that pre-date
+        // the waveIndex-in-filename change.
+        const key = data.waveIndex != null
+          ? `w${data.waveIndex}-${data.mergeNumber}`
+          : String(data.mergeNumber);
+        snapshots[key] = data;
       } catch { continue; }
     }
   } catch { /* dir missing */ }

package/extensions/taskplane/engine.ts

@@ -4225,14 +4225,23 @@ export async function executeOrchBatch(
 						"info",
 					);
 
-					// TP-040: Emit merge_success event
+					// TP-040: Emit merge_success event.
+					//
+					// `waveIndex` is the segment-round index (0-based), and the supervisor
+					// formatter renders the (N/M) counter using `waveIndex + 1` for N.
+					// For unit consistency we therefore pair it with the segment-level
+					// `batchState.totalWaves` (segment-expanded round count), not
+					// `taskLevelWaveCount` (pre-expansion). Using the task-level count as
+					// the denominator while the numerator counts segment rounds produced
+					// `(4/3)`, `(5/3)`, `(6/3)` style overflow once segments expanded —
+					// see issue #562.
 					emitEvent(
 						stateRoot,
 						{
 							...buildEngineEventBase("merge_success", batchState.batchId, waveIdx, batchState.phase),
 							laneCount: mergedCount,
 							durationMs: mergeResult.totalDurationMs,
-							totalWaves: taskLevelWaveCount,
+							totalWaves: batchState.totalWaves,
 						},
 						onEngineEvent,
 					);

package/extensions/taskplane/merge.ts

@@ -895,7 +895,7 @@ export async function spawnMergeAgentV2(
 				agent: buildAgentSnap(tel, "running"),
 				updatedAt: Date.now(),
 			};
-			writeMergeSnapshot(mergeStateRoot, bid, mergeNumber, snap);
+			writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
 		} catch {
 			/* non-fatal */
 		}
@@ -915,7 +915,7 @@ export async function spawnMergeAgentV2(
 			agent: buildAgentSnap({}, "running"),
 			updatedAt: Date.now(),
 		};
-		writeMergeSnapshot(mergeStateRoot, bid, mergeNumber, initialSnap);
+		writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, initialSnap);
 	} catch {
 		/* non-fatal */
 	}
@@ -964,7 +964,7 @@ export async function spawnMergeAgentV2(
 					agent: buildAgentSnap(result, terminalStatus === "complete" ? "exited" : "crashed"),
 					updatedAt: Date.now(),
 				};
-				writeMergeSnapshot(mergeStateRoot, bid, mergeNumber, snap);
+				writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
 			} catch {
 				/* non-fatal */
 			}
@@ -987,7 +987,7 @@ export async function spawnMergeAgentV2(
 					agent: buildAgentSnap({}, "crashed"),
 					updatedAt: Date.now(),
 				};
-				writeMergeSnapshot(mergeStateRoot, bid, mergeNumber, snap);
+				writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
 			} catch {
 				/* non-fatal */
 			}

package/extensions/taskplane/path-resolver.ts

@@ -112,32 +112,53 @@ const PI_PACKAGE_SCOPES = ["@earendil-works", "@mariozechner"] as const;
  * `dist/cli.js` so callers can spawn it with `node` directly, without a shell
  * intermediary.
  *
- * Resolution order: the cross product of base directories × package scopes,
- * with each base directory tried for the new scope before any base directory
- * is tried for the legacy scope. (Equivalently: scope is the inner loop, base
- * is the outer loop.)
+ * Resolution order:
+ *
+ *   0. **AUTHORITATIVE** — `process.argv[1]` when it points at a Pi `cli.js`.
+ *      When Taskplane is running as a Pi extension, the parent process IS
+ *      Pi, and Node sets `process.argv[1]` to the path of the file used to
+ *      start it. This is the single most reliable resolution path: it works
+ *      for npm-global, mise, asdf, NVM (Windows + Unix), Nix, Bun-installed
+ *      Pi, and any future install method we can't enumerate. Issues #519
+ *      and #598 both stem from this signal being ignored in favor of a
+ *      static-path search that misses non-canonical install layouts.
+ *
+ * If `process.argv[1]` isn't a Pi `cli.js` (e.g. running standalone in tests,
+ * or invoked through an indirect wrapper), the function falls through to a
+ * cross product of base directories × package scopes:
  *
- * Base directories (outer loop):
- *   1. `npm root -g` result (dynamic — covers all setups: nvm, Homebrew, volta, etc.)
+ *   1. `npm root -g` result (dynamic — covers npm-global, Homebrew, volta, etc.)
  *   2. `%APPDATA%\npm\node_modules\...` (Windows, APPDATA env var)
  *   3. `%USERPROFILE%\AppData\Roaming\npm\node_modules\...` (Windows, HOME-relative)
  *   4. `~/.npm-global/lib/node_modules/...` (macOS/Linux custom global prefix)
- *   5. `/usr/local/lib/node_modules/...` (macOS system Node, Linux)
- *   6. `/opt/homebrew/lib/node_modules/...` (macOS Homebrew)
+ *   5. `$NVM_SYMLINK\node_modules` (NVM-for-Windows, when the env var is set)
+ *   6. `dirname($NVM_BIN)/../lib/node_modules` (NVM-for-Unix, when the env var is set)
+ *   7. `/usr/local/lib/node_modules/...` (macOS system Node, Linux)
+ *   8. `/opt/homebrew/lib/node_modules/...` (macOS Homebrew)
  *
  * Scopes per base (inner loop):
  *   a. `@earendil-works/pi-coding-agent/dist/cli.js`
  *   b. `@mariozechner/pi-coding-agent/dist/cli.js`
  *
- * @returns Absolute path to a Pi CLI `dist/cli.js` (under whichever scope was found).
- * @throws  {Error} If the CLI entrypoint cannot be found under any base × scope
- *          combination. The error message includes the `npm root -g` value
- *          AND lists both scopes searched, for operator diagnosis.
+ * @returns Absolute path to a Pi CLI `dist/cli.js`.
+ * @throws  {Error} If the CLI entrypoint cannot be found by any strategy.
+ *          The error message includes the `npm root -g` value AND lists
+ *          both scopes searched, for operator diagnosis.
  */
 export function resolvePiCliPath(): string {
+	// 0. AUTHORITATIVE: trust process.argv[1] when it points at a Pi cli.js.
+	// Pi's package.json declares `"bin": { "pi": "dist/cli.js" }`, so the
+	// `endsWith("cli.js")` guard is a tight sanity check that rejects e.g.
+	// test runners or wrapper scripts that happen to leave argv[1] pointing
+	// somewhere else. existsSync() guards against stale argv state in mocks.
+	const piEntry = process.argv[1] || "";
+	if (piEntry.endsWith("cli.js") && existsSync(piEntry)) {
+		return piEntry;
+	}
+
 	const bases: string[] = [];
 
-	// 1. Dynamic: npm root -g (covers nvm, Homebrew, volta, custom npm prefix, etc.)
+	// 1. Dynamic: npm root -g (covers npm-global, Homebrew, volta, custom npm prefix, etc.)
 	const npmRoot = getNpmGlobalRoot();
 	if (npmRoot) bases.push(npmRoot);
 
@@ -151,9 +172,25 @@ export function resolvePiCliPath(): string {
 		// 4. macOS/Linux custom global prefix
 		bases.push(join(home, ".npm-global", "lib", "node_modules"));
 	}
-	// 5. macOS system Node / Linux
+
+	// 5. NVM-for-Windows defense in depth: NVM_SYMLINK points at the active
+	// Node install (typically C:\Program Files\nodejs as a junction), and the
+	// global packages live under <symlink>\node_modules. Child processes
+	// inherit this env var even when PATH is stripped of npm.
+	if (process.env.NVM_SYMLINK) {
+		bases.push(join(process.env.NVM_SYMLINK, "node_modules"));
+	}
+
+	// 6. NVM-for-Unix defense in depth: NVM_BIN points at the active version's
+	// bin directory, and the corresponding node_modules sit alongside it at
+	// `../lib/node_modules`. Same inheritance properties as NVM_SYMLINK.
+	if (process.env.NVM_BIN) {
+		bases.push(join(process.env.NVM_BIN, "..", "lib", "node_modules"));
+	}
+
+	// 7. macOS system Node / Linux
 	bases.push(join("/usr", "local", "lib", "node_modules"));
-	// 6. macOS Homebrew
+	// 8. macOS Homebrew
 	bases.push(join("/opt", "homebrew", "lib", "node_modules"));
 
 	// Cross product: scope is the inner loop so a single base directory is

package/extensions/taskplane/process-registry.ts

@@ -400,20 +400,25 @@ export function readLaneSnapshot(
  * Stored in the `lanes/` directory alongside lane snapshots so the dashboard
  * server picks it up with the same scan that reads lane-N.json files.
  *
+ * Filename includes BOTH waveIndex and mergeNumber so wave-N+1's merges
+ * cannot overwrite wave-N's snapshots before the dashboard polls them (#509).
+ *
  * @param stateRoot   - Repository root (where `.pi/` lives)
  * @param batchId     - Current batch identifier
+ * @param waveIndex   - 0-based wave index for the merge
  * @param mergeNumber - 1-indexed merge agent number
  * @param snapshot    - Snapshot data to persist
  *
- * @since TP-164
+ * @since TP-164 (waveIndex parameter added in #509 remediation)
  */
 export function writeMergeSnapshot(
 	stateRoot: string,
 	batchId: string,
+	waveIndex: number,
 	mergeNumber: number,
 	snapshot: RuntimeMergeSnapshot,
 ): void {
-	const path = runtimeMergeSnapshotPath(stateRoot, batchId, mergeNumber);
+	const path = runtimeMergeSnapshotPath(stateRoot, batchId, waveIndex, mergeNumber);
 	mkdirSync(dirname(path), { recursive: true });
 	const tmpPath = path + ".tmp";
 	writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
@@ -426,17 +431,19 @@ export function writeMergeSnapshot(
  *
  * @param stateRoot   - Repository root (where `.pi/` lives)
  * @param batchId     - Current batch identifier
+ * @param waveIndex   - 0-based wave index for the merge
  * @param mergeNumber - 1-indexed merge agent number
  *
- * @since TP-164
+ * @since TP-164 (waveIndex parameter added in #509 remediation)
  */
 export function readMergeSnapshot(
 	stateRoot: string,
 	batchId: string,
+	waveIndex: number,
 	mergeNumber: number,
 ): RuntimeMergeSnapshot | null {
 	try {
-		const p = runtimeMergeSnapshotPath(stateRoot, batchId, mergeNumber);
+		const p = runtimeMergeSnapshotPath(stateRoot, batchId, waveIndex, mergeNumber);
 		if (!existsSync(p)) return null;
 		return JSON.parse(readFileSync(p, "utf-8")) as RuntimeMergeSnapshot;
 	} catch {

package/extensions/taskplane/types.ts

@@ -4323,12 +4323,26 @@ export interface RuntimeMergeSnapshot {
  *
  * @since TP-164
  */
+/**
+ * Path to a merge agent snapshot file.
+ *
+ * The filename includes BOTH `waveIndex` and `mergeNumber` because lane
+ * numbers (and therefore the legacy `mergeNumber`-only filename) repeat
+ * across waves — a wave-2 lane-1 merge would overwrite the wave-1 lane-1
+ * snapshot before the dashboard's next poll could read it. Per-wave
+ * namespacing keeps each merge's snapshot durable until the runtime
+ * directory itself is cleaned up at end-of-batch. See #509.
+ *
+ * @param waveIndex   0-based wave index for the merge
+ * @param mergeNumber 1-based merge agent number (derived from lane number)
+ */
 export function runtimeMergeSnapshotPath(
 	stateRoot: string,
 	batchId: string,
+	waveIndex: number,
 	mergeNumber: number,
 ): string {
-	return `${stateRoot}/.pi/runtime/${batchId}/lanes/merge-${mergeNumber}.json`;
+	return `${stateRoot}/.pi/runtime/${batchId}/lanes/merge-w${waveIndex}-${mergeNumber}.json`;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.30.1",
+  "version": "0.30.3",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",