taskplane 0.30.0 → 0.30.2

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 ───────────────────────────────────────────────────────────
 
 /**
@@ -382,6 +393,53 @@ function taskSegmentProgress(task, segmentStatusMap, forcedActiveSegmentId) {
   };
 }
 
+// TP-197 (#464): Render a horizontal pill row of per-segment status badges for a
+// multi-segment task. Each pill shows an icon + repoId for one segment. The icon
+// reflects the segment's status (succeeded / running / pending / failed / stalled /
+// skipped). The current segment (the one actively executing on its lane) gets an
+// emphasis class. Returns "" for single-segment tasks so the rendered DOM is
+// byte-identical to today for the non-segmented common case (no regression).
+//
+// Consumes:
+//   - task.segmentIds: string[] (ordered, from PersistedTaskRecord)
+//   - segmentStatusMap: Map<segmentId, PersistedSegmentStatus> built by
+//     buildSegmentStatusMap() from batch.segments[]
+//   - activeSegmentId: string|null — current executing segment (from V2 lane
+//     snapshot's segmentId, or the task's activeSegmentId field)
+function taskSegmentPillRow(task, segmentStatusMap, activeSegmentId) {
+  const segmentIds = Array.isArray(task?.segmentIds)
+    ? task.segmentIds.filter(id => typeof id === "string")
+    : [];
+  if (segmentIds.length <= 1) return "";
+
+  // Status -> { icon, className } table. Keep emoji simple/monospace-friendly.
+  // ✅ succeeded, ⏳ running, ⬚ pending, ❌ failed, ⏸ stalled, ↷ skipped.
+  const styles = {
+    succeeded: { icon: "\u2705", cls: "seg-succeeded" },
+    running:   { icon: "\u23F3", cls: "seg-running" },
+    pending:   { icon: "\u2B1A", cls: "seg-pending" },
+    failed:    { icon: "\u274C", cls: "seg-failed" },
+    stalled:   { icon: "\u23F8", cls: "seg-stalled" },
+    skipped:   { icon: "\u21B7", cls: "seg-skipped" },
+  };
+
+  const pills = segmentIds.map((segId) => {
+    const status = segmentStatusMap.get(segId) || "pending";
+    const style = styles[status] || styles.pending;
+    const parsed = parseSegmentId(segId);
+    const repoLabel = parsed?.repoId || segId;
+    const isCurrent = activeSegmentId && segId === activeSegmentId;
+    const currentCls = isCurrent ? " seg-pill-current" : "";
+    const title = `${segId} \u00b7 ${status}`;
+    return `<span class="seg-pill ${style.cls}${currentCls}" title="${escapeHtml(title)}">`
+      + `<span class="seg-pill-icon">${style.icon}</span>`
+      + `<span class="seg-pill-label">${escapeHtml(repoLabel)}</span>`
+      + `</span>`;
+  }).join("");
+
+  return `<div class="task-segment-row">${pills}</div>`;
+}
+
 function laneActiveSegmentInfo(v2snap, laneTasks, segmentStatusMap) {
   if (!v2snap || !v2snap.segmentId) return null;
   const parsed = parseSegmentId(v2snap.segmentId);
@@ -620,7 +678,13 @@ function renderSummary(batch) {
       // their assigned lane: tasks on the same lane render with `→` (serial),
       // tasks on different lanes render with ` | ` (parallel). Tooltip shows
       // the expanded lane breakdown.
-      const { compact, tooltip } = formatWaveLaneBreakdown(taskIds, batch.lanes || [], i + 1);
+      // TP-197 post-merge fold: pass `batch.tasks` as the task→lane source.
+      // The previous arg `batch.lanes` only carries live Runtime V2 lane
+      // state for the *currently active* wave — past/future wave chips
+      // would fall back to comma-separated. `batch.tasks[].laneNumber` is
+      // persisted for the entire batch lifecycle, so all waves render with
+      // the correct parallelization separator regardless of active state.
+      const { compact, tooltip } = formatWaveLaneBreakdown(taskIds, batch.lanes || [], batch.tasks || [], i + 1);
       const titleAttr = tooltip ? ` title="${escapeHtml(tooltip)}"` : "";
       wavesHtml += `<span class="wave-chip ${cls}"${titleAttr}>W${i + 1} [${compact}]</span>`;
     });
@@ -648,16 +712,46 @@ function renderSummary(batch) {
  * are shown with the previous flat formatting and no tooltip is generated
  * — this preserves backward compatibility with future-wave display.
  */
-function formatWaveLaneBreakdown(taskIds, lanes, waveNumber) {
+function formatWaveLaneBreakdown(taskIds, lanes, tasks, waveNumber) {
   if (!Array.isArray(taskIds) || taskIds.length === 0) {
     return { compact: "", tooltip: "" };
   }
-  // Build taskId → laneNumber map for the lanes that have any of these tasks.
+  // Build taskId → laneNumber map. Prefer the persisted-per-task
+  // `tasks[i].laneNumber` (covers all waves, lifecycle-stable). Fall back
+  // to live `lanes[]` only when tasks data is missing or doesn't carry
+  // laneNumber for a given task.
+  //
+  // TP-197 post-merge fold: the previous implementation read ONLY from
+  // `lanes`, which is Runtime V2 live state and only populated for the
+  // currently active wave. That caused inactive waves' chips to fall back
+  // to comma-separated display (no parallelization indicator), giving the
+  // impression that the separator changed as the batch progressed. Using
+  // the persisted `tasks[].laneNumber` makes the indicator stable across
+  // all waves regardless of active state.
   const taskToLane = new Map();
+  if (Array.isArray(tasks)) {
+    for (const t of tasks) {
+      // Persistence assigns `laneNumber: 0` as a sentinel meaning
+      // "unallocated" (see persistence.ts:1378 — `lane?.laneNumber ??
+      // outcome?.laneNumber ?? 0`). Real lane numbers start at 1. We must
+      // skip 0 here so future-wave tasks (which all have the 0 sentinel
+      // until their wave starts) don't get falsely grouped under a fake
+      // "lane 0" and rendered as serial.
+      if (
+        t &&
+        t.taskId &&
+        typeof t.laneNumber === "number" &&
+        t.laneNumber >= 1 &&
+        !taskToLane.has(t.taskId)
+      ) {
+        taskToLane.set(t.taskId, t.laneNumber);
+      }
+    }
+  }
+  // Fallback: anything `tasks` didn't cover, try `lanes` (live state).
   for (const lane of lanes) {
     if (!lane || !Array.isArray(lane.taskIds)) continue;
     for (const tid of lane.taskIds) {
-      // First lane to claim a task wins (lanes shouldn't overlap, but be defensive).
       if (!taskToLane.has(tid)) taskToLane.set(tid, lane.laneNumber);
     }
   }
@@ -859,8 +953,24 @@ function renderLanesTasks(batch, sessions) {
         stepHtml = `<span style="color:var(--text-faint)">${escapeHtml(task.exitReason || "—")}</span>`;
       }
 
+      // TP-197 (#464): Compute the per-segment pill row for multi-segment tasks.
+      // Returns "" for single-segment tasks (no DOM regression for the common case).
+      // For multi-segment tasks we render the pill row in the task-row's grid row 3
+      // (via .task-segment-row CSS) and suppress the inline "Segment N/T: repo" text
+      // in detailBits to avoid duplicating signal — the pill row already shows the
+      // current segment (via seg-pill-current) and total count (via pill count).
+      const segmentPillRowHtml = taskSegmentPillRow(
+        task,
+        segmentStatusMap,
+        v2snap && v2snap.taskId === task.taskId ? v2snap.segmentId : (segmentInfo?.segmentId || null),
+      );
+      const hasSegmentPillRow = segmentPillRowHtml !== "";
+
       const detailBits = [];
-      if (segmentInfo) {
+      if (segmentInfo && !hasSegmentPillRow) {
+        // Single-segment + non-segmented tasks: existing inline text (unchanged).
+        // Multi-segment tasks: suppressed because the new pill row carries the same
+        // information more legibly.
         detailBits.push(`<span class="task-segment-progress" title="${escapeHtml(segmentInfo.segmentId || segmentProgressText(segmentInfo))}">${escapeHtml(segmentProgressText(segmentInfo))}</span>`);
       }
       if (showPacketHome) {
@@ -950,8 +1060,17 @@ function renderLanesTasks(batch, sessions) {
       const titleHtml = task.taskTitle
         ? `<div class="task-title-subtitle">${escapeHtml(task.taskTitle)}</div>`
         : "";
+      // TP-197 (#464): segmentPillRowHtml is empty for single-segment tasks so
+      // the rendered DOM is byte-identical to today for non-segmented tasks.
+      // For multi-segment tasks it renders as grid-row 3 of .task-row.
+      // Sage post-merge fold: the .has-segments class opts the .task-row
+      // grid into a 3-row template only when we actually have a pill row;
+      // otherwise the default 2-row template preserves single-segment task
+      // spacing exactly (an unconditional 3-row template would add an 8px
+      // row-gap even when row 3 is empty, breaking the no-regression contract).
+      const taskRowClass = hasSegmentPillRow ? "task-row has-segments" : "task-row";
       html += `
-        <div class="task-row">
+        <div class="${taskRowClass}">
           <span class="task-icon"><span class="status-dot ${task.status}"></span></span>
           <span class="task-actions">${eyeHtml}</span>
           <span class="task-id status-${task.status}">${escapeHtml(task.taskId)}${showRepos ? repoBadgeHtml(tRepo, "repo-badge-task") : ""}</span>
@@ -960,6 +1079,7 @@ function renderLanesTasks(batch, sessions) {
           <span>${progressHtml}</span>
           <span class="task-step">${stepHtml}${workerHtml}</span>
           ${titleHtml}
+          ${segmentPillRowHtml}
         </div>`;
       html += reviewerRowHtml;
     }
@@ -1054,7 +1174,15 @@ function renderMergeAgents(batch, sessions) {
   }
 
   let html = '<table class="merge-table"><thead><tr>';
-  html += '<th>Wave</th><th>Status</th><th>Session</th><th>Telemetry</th><th>Session ID</th><th>Details</th>';
+  // TP-197 post-merge fold: removed 'Session ID' and 'Details' columns.
+  // SESSION ID was hardcoded to '—' in every row — dead weight.
+  // DETAILS only populated for `mr.failureReason` (rare failure cases);
+  // for the common all-merges-succeeded case it's always '—' too.
+  // When a real failure happens, the operator sees status='failed' in
+  // the Status column and can dig into engine logs for the reason —
+  // we'll re-add a focused DETAILS column if/when we have meaningful
+  // structured failure-reason data to surface in the dashboard table.
+  html += '<th>Wave</th><th>Status</th><th>Session</th><th>Telemetry</th>';
   html += '</tr></thead><tbody>';
 
   // Track sessions shown in wave result rows so we don't duplicate them below
@@ -1135,10 +1263,6 @@ function renderMergeAgents(batch, sessions) {
     html += `<td class="merge-session-cell">${effectiveAlive ? escapeHtml(effectiveSession) : "—"}</td>`;
     // Full telemetry cell
     html += `<td class="merge-telemetry-cell">${mergeTelemetryHtml(mergeTel, effectiveAlive)}</td>`;
-    html += `<td>`;
-    html += '<span class="merge-no-data">—</span>';
-    html += `</td>`;
-    html += `<td class="merge-detail-cell">${mr.failureReason ? escapeHtml(mr.failureReason) : "—"}</td>`;
     html += `</tr>`;
 
     // Per-repo sub-rows: show when workspace mode has repo results
@@ -1159,8 +1283,6 @@ function renderMergeAgents(batch, sessions) {
         html += `<td><span class="status-badge ${rrStatusCls}">${rr.status}</span></td>`;
         html += `<td class="merge-session-cell">${rrLanes}</td>`;
         html += `<td></td>`; /* telemetry placeholder */
-        html += `<td></td>`; /* attach placeholder */
-        html += `<td class="merge-detail-cell">${rrDetail}</td>`;
         html += `</tr>`;
       }
     }
@@ -1177,8 +1299,6 @@ function renderMergeAgents(batch, sessions) {
     html += `<td class="merge-session-cell">${escapeHtml(sess)}</td>`;
     // Full telemetry cell for active merge session
     html += `<td class="merge-telemetry-cell">${mergeTelemetryHtml(sessTel, true)}</td>`;
-    html += `<td>—</td>`;
-    html += `<td>—</td>`;
     html += `</tr>`;
   }
 
@@ -1709,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;
@@ -1721,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/public/style.css

@@ -608,7 +608,13 @@ body {
   display: grid;
   grid-template-columns: 36px 24px 100px 90px 80px 200px 1fr;
   /* #485 (revised): row 1 holds the primary cells; row 2 (auto, collapses to
-   * 0 when empty) holds the optional task-title-subtitle spanning cols 3–6. */
+   * 0 when empty) holds the optional task-title-subtitle spanning cols 3–6.
+   * Default: 2 rows. TP-197 (#464) adds the optional per-segment pill row in
+   * grid-row 3 ONLY when the .has-segments class is set (multi-segment tasks).
+   * Non-segmented tasks keep the pre-TP-197 2-row layout exactly — 'auto'
+   * row tracks don't fully collapse with row-gap declared, so adding a third
+   * row track unconditionally would introduce an 8px visible gap for every
+   * single-segment task (sage post-merge fold). */
   grid-template-rows: auto auto;
   align-items: center;
   gap: 8px 8px;
@@ -617,6 +623,13 @@ body {
   transition: background 0.15s;
 }
 
+/* TP-197 (#464): multi-segment tasks opt-in to a 3-row grid for the segment-
+ * pill row. JS adds .has-segments to .task-row only when the pill row is
+ * non-empty (see app.js taskSegmentPillRow + task-row template). */
+.task-row.has-segments {
+  grid-template-rows: auto auto auto;
+}
+
 .task-row:last-child { border-bottom: none; }
 .task-row:hover { background: var(--bg-surface-hover); }
 
@@ -652,6 +665,71 @@ body {
   margin-top: -2px;
 }
 
+/* ─── TP-197 (#464): Per-segment pill row for multi-segment tasks ─────── */
+
+.task-segment-row {
+  /* Sub-row beneath the primary task row, mirroring the title-subtitle pattern
+   * (TP-485). Spans cols 3 → 7 so it shares the title area's horizontal space.
+   * Placed at grid row 3 so it sits *below* the optional title-subtitle.
+   * Container collapses to 0 height when not rendered (single-segment tasks),
+   * so non-segmented tasks render with identical row height to today.
+   * Lives OUTSIDE .task-step intentionally so the @media (max-width: 900px)
+   * rule that hides .task-step does NOT hide the pill row — keeps segment
+   * context visible at narrow viewports. */
+  grid-column: 3 / 7;
+  grid-row: 3;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  margin-top: 2px;
+  min-width: 0;
+}
+
+.seg-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-family: var(--font-mono);
+  font-size: 0.68rem;
+  font-weight: 500;
+  line-height: 1.4;
+  padding: 1px 7px;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  max-width: 140px;
+  white-space: nowrap;
+}
+
+.seg-pill .seg-pill-icon {
+  font-size: 0.72rem;
+  line-height: 1;
+  flex-shrink: 0;
+}
+
+.seg-pill .seg-pill-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+}
+
+/* Status variants — reuse the existing status-badge color tokens for
+ * consistency with .status-badge.status-{succeeded,running,failed,…}. */
+.seg-pill.seg-succeeded { background: var(--badge-succeeded-bg); color: var(--green); }
+.seg-pill.seg-running   { background: var(--badge-running-bg);   color: var(--accent); }
+.seg-pill.seg-pending   { background: var(--bg-surface);         color: var(--text-muted); border-color: var(--border-default, var(--border-subtle)); }
+.seg-pill.seg-failed    { background: var(--badge-failed-bg);    color: var(--red); }
+.seg-pill.seg-stalled   { background: var(--badge-failed-bg);    color: var(--yellow, var(--red)); opacity: 0.85; }
+.seg-pill.seg-skipped   { background: var(--bg-surface);         color: var(--text-muted); opacity: 0.7; }
+
+/* Current-segment emphasis: brighter border + slight weight bump so operator
+ * can spot "we're here right now" at a glance independent of icon. */
+.seg-pill.seg-pill-current {
+  border-color: var(--accent);
+  font-weight: 600;
+  box-shadow: 0 0 0 1px var(--accent-dim, transparent);
+}
+
 .task-duration {
   font-family: var(--font-mono);
   font-size: 0.8rem;
@@ -783,7 +861,10 @@ body {
   font-weight: 600;
   text-transform: uppercase;
   letter-spacing: 0.05em;
-  color: var(--text-faint);
+  /* TP-197 post-merge fold: bumped --text-faint → --text-muted for
+   * readability. Matches other dashboard section headers (lines 224, 248,
+   * 458 of this file already use --text-muted for the same role). */
+  color: var(--text-muted);
   border-bottom: 1px solid var(--border);
   background: var(--bg-surface);
 }

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/discovery.ts

@@ -809,6 +809,41 @@ export function parsePromptForOrchestrator(
 
 // ── Area Scanning ────────────────────────────────────────────────────
 
+/**
+ * TP-196 / #462 — Discovery safeguard for `.DONE` authority drift.
+ *
+ * Discovery has no access to persisted segment state, so it cannot make a
+ * hard `.DONE` vs. segment-frontier authority decision (that lives in the
+ * monitor/resume guards). What it CAN do cheaply is detect the most common
+ * symptom of a stale or premature `.DONE`: a `.DONE` file exists alongside
+ * a STATUS.md that still has unchecked checkboxes. When that pattern is
+ * found, emit a one-line `console.warn` so operators see the inconsistency
+ * during scan. Behaviour of `scanAreaForTasks` is unchanged — the task is
+ * still skipped — this is a doctor-style warning only.
+ *
+ * Returns `true` when the safeguard issued a warning (used by tests).
+ */
+export function checkDoneAuthoritySafeguard(
+	taskFolder: string,
+	logger: (msg: string) => void = console.warn,
+): boolean {
+	const statusPath = join(taskFolder, "STATUS.md");
+	if (!existsSync(statusPath)) return false;
+	let content: string;
+	try {
+		content = readFileSync(statusPath, "utf-8");
+	} catch {
+		return false;
+	}
+	// Look for any unchecked checkbox `- [ ]` on its own line.
+	const hasUnchecked = /^\s*-\s*\[\s\]\s+/m.test(content);
+	if (!hasUnchecked) return false;
+	logger(
+		`[discovery] WARN: .DONE present in ${taskFolder} but STATUS.md contains unchecked checkboxes — possible stale/premature .DONE (#462 safeguard).`,
+	);
+	return true;
+}
+
 /**
  * Scan an area path for pending tasks.
  *
@@ -858,8 +893,14 @@ export function scanAreaForTasks(
 			continue;
 		}
 
-		// Skip if .DONE exists (already complete)
-		if (existsSync(join(entryPath, ".DONE"))) continue;
+		// Skip if .DONE exists (already complete).
+		// TP-196 / #462: doctor-style safeguard — if .DONE coexists with
+		// unchecked checkboxes in STATUS.md, warn so operators can investigate
+		// before the task is silently treated as complete.
+		if (existsSync(join(entryPath, ".DONE"))) {
+			checkDoneAuthoritySafeguard(entryPath);
+			continue;
+		}
 
 		// Skip if no PROMPT.md
 		const promptPath = join(entryPath, "PROMPT.md");

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/execution.ts

@@ -885,6 +885,13 @@ async function parseStatusMdContent(
  * @param tracker        - Mtime tracker for stall detection
  * @param stallTimeoutMs - Stall timeout in milliseconds
  * @param now            - Current timestamp (epoch ms) for deterministic testing
+ * @param multiSegmentContext - Optional segment-authority context (TP-196 / #462).
+ *                              When provided AND `isFinalSegment === false`,
+ *                              `.DONE` is treated as a non-authoritative signal
+ *                              (Priority 1 is skipped). This guards against a
+ *                              stale or premature `.DONE` from a non-final
+ *                              segment short-circuiting the task to succeeded
+ *                              before the remaining segments have run.
  */
 export async function resolveTaskMonitorState(
 	taskId: string,
@@ -896,6 +903,7 @@ export async function resolveTaskMonitorState(
 	now: number,
 	runtimeBackend?: RuntimeBackend,
 	v2Context?: { stateRoot: string; batchId: string; laneNumber: number },
+	multiSegmentContext?: { isFinalSegment: boolean; segmentId: string },
 ): Promise<TaskMonitorSnapshot> {
 	// TP-115/TP-127: Backend-aware liveness check.
 	// V2: read the lane snapshot file written by lane-runner every second.
@@ -1035,7 +1043,27 @@ export async function resolveTaskMonitorState(
 	}
 
 	// ── Priority 1: .DONE file found → succeeded ────────────────
-	if (doneFileFound) {
+	// TP-196 / #462: Monitor guard for multi-segment tasks. When the caller
+	// has provided a segment-authority context AND tells us the active segment
+	// is NOT the final segment in the task plan, `.DONE` MUST NOT be accepted
+	// as authoritative — a non-final segment's worker should never have
+	// produced one. We log a WARN and fall through to the lower priorities
+	// (which keep the task in a non-terminal state so the engine can recover).
+	const doneAcceptedAsAuthority =
+		doneFileFound && !(multiSegmentContext && multiSegmentContext.isFinalSegment === false);
+	if (doneFileFound && !doneAcceptedAsAuthority) {
+		execLog(
+			"monitor",
+			taskId,
+			`WARN: .DONE present for non-final segment '${multiSegmentContext?.segmentId}' — ignoring (#462 guard)`,
+			{
+				session: sessionName,
+				segmentId: multiSegmentContext?.segmentId,
+				donePath,
+			},
+		);
+	}
+	if (doneAcceptedAsAuthority) {
 		return {
 			taskId,
 			status: "succeeded",
@@ -1315,6 +1343,19 @@ export async function monitorLanes(
 					const statusPath = unit.packet.statusPath;
 					const statusResult = await parseStatusMdAtPath(statusPath);
 
+					// TP-196 / #462: Build multi-segment authority context so
+					// `.DONE` from a non-final segment is not accepted as terminal.
+					const taskSegmentIds = task.task.segmentIds ?? [];
+					const taskActiveSegmentId = task.task.activeSegmentId ?? null;
+					let multiSegmentContext: { isFinalSegment: boolean; segmentId: string } | undefined;
+					if (taskSegmentIds.length > 1 && taskActiveSegmentId) {
+						const finalSegmentId = taskSegmentIds[taskSegmentIds.length - 1];
+						multiSegmentContext = {
+							isFinalSegment: taskActiveSegmentId === finalSegmentId,
+							segmentId: taskActiveSegmentId,
+						};
+					}
+
 					const snapshot = await resolveTaskMonitorState(
 						task.taskId,
 						donePath,
@@ -1331,6 +1372,7 @@ export async function monitorLanes(
 									laneNumber: lane.laneNumber,
 								}
 							: undefined,
+						multiSegmentContext,
 					);
 
 					currentTaskSnapshot = snapshot;

package/extensions/taskplane/lane-runner.ts

@@ -68,6 +68,7 @@ import {
 	type LaneTaskStatus,
 	type SupervisorAlertCallback,
 	type StepSegmentMapping,
+	type SegmentScopeMode,
 } from "./types.ts";
 
 const LANE_RUNNER_DIR = dirname(fileURLToPath(import.meta.url));
@@ -178,6 +179,75 @@ export function isSegmentComplete(
 	return result.unchecked === 0;
 }
 
+/**
+ * Compute the authoritative `SegmentScopeMode` for one worker iteration.
+ *
+ * This is the single source of truth for the FULL_TASK vs SEGMENT_SCOPED
+ * decision (TP-196 / #502). All segment-related side-effects (env vars,
+ * system-prompt overlay, prompt content, tool registration) should derive
+ * their behaviour from this mode rather than re-evaluating the underlying
+ * boolean conditions in isolation, which is what created the drift risk
+ * documented in #502.
+ *
+ * Returns `SEGMENT_SCOPED` iff ALL of the following hold:
+ *  - The task has a non-empty `stepSegmentMap` (parsed from PROMPT.md markers).
+ *  - The lane has an associated `currentRepoId` (segmentId set, so we know
+ *    which repo this lane is iterating).
+ *  - The (legacy-fallback-filtered) `repoStepNumbers` set is non-null (the
+ *    repo has at least one step with explicit segment markers).
+ *  - A `currentStepNumber` is provided (there is a step to evaluate).
+ *  - The current step's segment mapping contains an entry for `currentRepoId`
+ *    (the worker actually has segment-scoped work in the current step).
+ *
+ * In any other case the mode is `FULL_TASK`.
+ *
+ * @since TP-196
+ */
+export function computeSegmentScopeMode(
+	stepSegmentMap: StepSegmentMapping[] | undefined | null,
+	repoStepNumbers: Set<number> | null,
+	currentRepoId: string | null,
+	currentStepNumber: number | null,
+): SegmentScopeMode {
+	if (!stepSegmentMap || !currentRepoId || !repoStepNumbers) return "FULL_TASK";
+	if (currentStepNumber === null) return "FULL_TASK";
+	const currentStepMapping = stepSegmentMap.find((s) => s.stepNumber === currentStepNumber);
+	if (!currentStepMapping) return "FULL_TASK";
+	const mySegment = currentStepMapping.segments.find((seg) => seg.repoId === currentRepoId);
+	return mySegment ? "SEGMENT_SCOPED" : "FULL_TASK";
+}
+
+/**
+ * Pre-spawn segment-completion check (TP-196 / #508).
+ *
+ * Returns `true` when the lane-runner iteration loop should SKIP spawning
+ * a worker because all of the segment's checkboxes for this repo are
+ * already complete. The lane should `break` out of its iteration loop and
+ * fall through to post-loop completion handling.
+ *
+ * Contract:
+ *  - Returns `false` for FULL_TASK iterations (`currentRepoId === null` or
+ *    `repoStepNumbers === null` or empty). Those rely on the existing
+ *    `remainingSteps.length === 0` exit, not this check.
+ *  - Returns `true` iff EVERY step in `repoStepNumbers` is
+ *    `isSegmentComplete(statusContent, stepNum, currentRepoId)`.
+ *
+ * Pure function: no filesystem access, no global state. The caller reads
+ * the STATUS.md content once per iteration and passes it in.
+ *
+ * @since TP-196
+ */
+export function shouldSkipSpawnForCompleteSegment(
+	statusContent: string,
+	repoStepNumbers: Set<number> | null,
+	currentRepoId: string | null,
+): boolean {
+	if (!repoStepNumbers || !currentRepoId || repoStepNumbers.size === 0) return false;
+	return [...repoStepNumbers].every((stepNum) =>
+		isSegmentComplete(statusContent, stepNum, currentRepoId),
+	);
+}
+
 // ── Types ────────────────────────────────────────────────────────────
 
 /**
@@ -418,6 +488,27 @@ export async function executeTaskV2(
 
 		if (remainingSteps.length === 0) break; // All done
 
+		// TP-196 / #508: Pre-spawn segment-completion check.
+		//
+		// When the lane is iterating a segment-scoped task, verify that NOT ALL
+		// `repoStepNumbers` are segment-complete before incurring the cost of
+		// spawning a worker. The `remainingSteps` filter above already enforces
+		// this implicitly (via `isSegmentComplete`), but expressing the check
+		// explicitly at the spawn boundary:
+		//   1. Makes the wasted-iteration prevention contract visible.
+		//   2. Provides a defensive backstop for cases where `parsed.steps` and
+		//      `repoStepNumbers` diverge (e.g., legacy/partial-marker tasks).
+		//   3. Gives behavioural tests a clean assertion target (via the pure
+		//      helper `shouldSkipSpawnForCompleteSegment`).
+		if (shouldSkipSpawnForCompleteSegment(iterStatusContent, repoStepNumbers, currentRepoId)) {
+			logExecution(
+				statusPath,
+				"Pre-spawn segment-completion check",
+				`all segment checkboxes already complete for repo '${currentRepoId}' — skipping worker spawn (#508)`,
+			);
+			break;
+		}
+
 		totalIterations++;
 		updateStatusField(
 			statusPath,
@@ -454,16 +545,16 @@ export async function executeTaskV2(
 				/* ignore */
 			}
 
-		// TP-174/TP-501: Compute segment scope mode BEFORE building prompt.
-		const isSegmentScoped = !!(
-			stepSegmentMap &&
-			currentRepoId &&
-			repoStepNumbers &&
-			remainingSteps.length > 0 &&
-			stepSegmentMap
-				.find((s) => s.stepNumber === remainingSteps[0].number)
-				?.segments.find((seg) => seg.repoId === currentRepoId)
+		// TP-174/TP-501/TP-196: Compute segment scope mode BEFORE building prompt.
+		// `segmentScopeMode` is the authoritative TP-196 flag; `isSegmentScoped` is
+		// preserved as a boolean alias for ergonomics at the many existing call sites.
+		const segmentScopeMode: SegmentScopeMode = computeSegmentScopeMode(
+			stepSegmentMap,
+			repoStepNumbers,
+			currentRepoId,
+			remainingSteps.length > 0 ? remainingSteps[0].number : null,
 		);
+		const isSegmentScoped = segmentScopeMode === "SEGMENT_SCOPED";
 
 		const promptLines = [
 			`Read your task instructions at: ${promptPath}`,
@@ -513,16 +604,27 @@ export async function executeTaskV2(
 		// Segment scope mode is determined by which system prompt was loaded.
 		// No SegmentScopeMode line needed — the prompt IS the mode.
 
-		// TP-174: Segment-scoped prompt — show only this segment's checkboxes
-		if (stepSegmentMap && currentRepoId && repoStepNumbers && remainingSteps.length > 0) {
+		// TP-174/TP-196: Segment-scoped prompt — show only this segment's checkboxes.
+		// Gated on the authoritative `isSegmentScoped` (derived from `segmentScopeMode`)
+		// rather than the raw composite condition, so the prompt branch can't drift
+		// from the mode decision (TP-196 / #502).
+		if (isSegmentScoped) {
 			const currentStepNum = remainingSteps[0].number;
-			const currentStepMapping = stepSegmentMap.find((s) => s.stepNumber === currentStepNum);
+			// Defensive guards: when `isSegmentScoped === true`, `computeSegmentScopeMode`
+			// has already verified `stepSegmentMap`, `currentRepoId`, and that the
+			// current step's mapping contains an entry for the active repo. We re-fetch
+			// the structures here for clarity. If any are missing we log and skip the
+			// segment block (defense-in-depth — should never trip in practice).
+			const currentStepMapping = stepSegmentMap?.find((s) => s.stepNumber === currentStepNum);
 			const mySegment = currentStepMapping?.segments.find((seg) => seg.repoId === currentRepoId);
 
-			// Only inject segment-scoped prompt when the current step has an explicit
-			// segment for this repoId. If mySegment is missing (legacy task without
-			// markers, or step has no work for this repo), skip and preserve legacy behavior.
-			if (currentStepMapping && mySegment) {
+			if (!currentStepMapping || !mySegment) {
+				logExecution(
+					statusPath,
+					"WARN",
+					`segmentScopeMode === SEGMENT_SCOPED but current step mapping missing — skipping segment prompt block (currentRepoId=${currentRepoId}, stepNum=${currentStepNum})`,
+				);
+			} else {
 				const otherSegments = currentStepMapping.segments.filter((seg) => seg.repoId !== currentRepoId);
 
 				// Count total segments for this repo across all steps

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/resume.ts

@@ -295,11 +295,40 @@ export function collectAllRepoRoots(
 
 // ── Resume Pure Functions ────────────────────────────────────────────
 
+/**
+ * Determine whether a multi-segment task's persisted segment frontier is
+ * complete — i.e., every segment for the task reached a terminal-success
+ * status ("succeeded" or "skipped").
+ *
+ * Returns:
+ *  - `true` when the task has segments AND all of them are terminal-success.
+ *  - `true` when the task has no segments recorded (single-segment / legacy
+ *    tasks — the guard does not apply and `.DONE` is authoritative).
+ *  - `false` when at least one segment is pending/running/failed/stalled.
+ *
+ * Used by `collectDoneTaskIdsForResume` (TP-196 / #462) to refuse a stale or
+ * premature `.DONE` from suppressing re-execution of remaining segments.
+ */
+function isSegmentFrontierCompleteForResume(
+	persistedState: PersistedBatchState,
+	taskId: string,
+): boolean {
+	const segments = (persistedState.segments ?? []).filter((s) => s.taskId === taskId);
+	if (segments.length === 0) return true; // No segments recorded — guard does not apply.
+	return segments.every((s) => s.status === "succeeded" || s.status === "skipped");
+}
+
 /**
  * Collect task IDs with authoritative .DONE markers.
  *
- * Segment frontier state does not suppress .DONE authority. If a marker exists,
- * resume reconciliation will mark the task complete regardless of segment state.
+ * Segment frontier state does not suppress .DONE authority for tasks WITHOUT
+ * persisted segment records (single-segment / legacy). For tasks WITH segment
+ * records (multi-segment), TP-196 / #462 adds a resume guard: when `.DONE`
+ * exists but the segment frontier is incomplete (at least one segment is not
+ * yet succeeded/skipped), we DO NOT add the taskId to the done set — the
+ * task will be re-reconciled instead of silently marked complete. A WARN is
+ * logged so operators can spot the inconsistency. The on-disk `.DONE` marker
+ * is left alone; the engine will re-establish authoritative state.
  */
 export function collectDoneTaskIdsForResume(
 	persistedState: PersistedBatchState,
@@ -308,22 +337,38 @@ export function collectDoneTaskIdsForResume(
 ): Set<string> {
 	const doneTaskIds = new Set<string>();
 	for (const task of persistedState.tasks) {
+		let markerFound = false;
+		let markerLocation: string | null = null;
 		if (task.taskFolder && hasTaskDoneMarker(task.taskFolder)) {
-			doneTaskIds.add(task.taskId);
-			continue;
+			markerFound = true;
+			markerLocation = task.taskFolder;
+		}
+		if (!markerFound) {
+			const laneRec = persistedState.lanes.find((l) => l.taskIds.includes(task.taskId));
+			if (laneRec?.worktreePath && task.taskFolder) {
+				const resolved = resolveCanonicalTaskPaths(
+					task.taskFolder,
+					laneRec.worktreePath,
+					repoRoot,
+					!!workspaceConfig,
+				);
+				if (existsSync(resolved.donePath)) {
+					markerFound = true;
+					markerLocation = resolved.donePath;
+				}
+			}
 		}
-		const laneRec = persistedState.lanes.find((l) => l.taskIds.includes(task.taskId));
-		if (laneRec?.worktreePath && task.taskFolder) {
-			const resolved = resolveCanonicalTaskPaths(
-				task.taskFolder,
-				laneRec.worktreePath,
-				repoRoot,
-				!!workspaceConfig,
+		if (!markerFound) continue;
+
+		// TP-196 / #462: Resume guard — refuse `.DONE` authority for multi-segment
+		// tasks with an incomplete segment frontier.
+		if (!isSegmentFrontierCompleteForResume(persistedState, task.taskId)) {
+			console.warn(
+				`[resume] WARN: .DONE present for task ${task.taskId} at ${markerLocation} but segment frontier is incomplete — not marking complete (#462 guard). Task will re-reconcile.`,
 			);
-			if (existsSync(resolved.donePath)) {
-				doneTaskIds.add(task.taskId);
-			}
+			continue;
 		}
+		doneTaskIds.add(task.taskId);
 	}
 	return doneTaskIds;
 }

package/extensions/taskplane/types.ts

@@ -180,6 +180,29 @@ export function buildExpansionRequestId(timestamp = Date.now()): string {
 
 // ── Step-Segment Mapping (Phase A: segment-scoped worker visibility) ────
 
+/**
+ * Authoritative segment-scope mode for a single worker iteration.
+ *
+ * - `FULL_TASK`: the worker sees the entire PROMPT.md, all steps, all checkboxes.
+ *   No `Active segment ID` / `Your checkboxes for this step` prose is injected.
+ *   Segment-related environment variables (`TASKPLANE_ACTIVE_SEGMENT_ID`,
+ *   `TASKPLANE_SEGMENT_ID`) are hard-cleared so that runtime tools keyed on
+ *   them (e.g., `request_segment_expansion`) cannot accidentally register.
+ *
+ * - `SEGMENT_SCOPED`: the worker is iterating a specific segment of a
+ *   multi-segment task. Only that segment's steps and checkboxes are shown;
+ *   `Active segment ID` is announced; segment-related env vars carry the
+ *   active `segmentId`; the segment-overlay system prompt is appended.
+ *
+ * This is the single authoritative flag for the segment-scope decision
+ * (TP-196 / #502). Call sites should derive their behaviour from this mode
+ * rather than re-evaluating the underlying boolean conditions, which prevents
+ * the multiple branches drifting out of sync.
+ *
+ * @since TP-196
+ */
+export type SegmentScopeMode = "FULL_TASK" | "SEGMENT_SCOPED";
+
 /** A group of checkboxes scoped to a single repo within a step. */
 export interface SegmentCheckboxGroup {
 	repoId: string;
@@ -4300,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.0",
+  "version": "0.30.2",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",