taskplane 0.30.0 → 0.30.1

package/dashboard/public/app.js

@@ -382,6 +382,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 +667,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 +701,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 +942,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 +1049,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 +1068,7 @@ function renderLanesTasks(batch, sessions) {
           <span>${progressHtml}</span>
           <span class="task-step">${stepHtml}${workerHtml}</span>
           ${titleHtml}
+          ${segmentPillRowHtml}
         </div>`;
       html += reviewerRowHtml;
     }
@@ -1054,7 +1163,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 +1252,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 +1272,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 +1288,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>`;
   }
 

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/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/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/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;

package/package.json

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