gsd-pi 2.81.0 → 2.82.0

package/dist/resources/extensions/gsd/bootstrap/register-shortcuts.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Registers GSD keyboard shortcuts for dashboard, notifications, and parallel overlays.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { Key } from "@gsd/pi-tui";
@@ -29,16 +31,10 @@ export function registerShortcuts(pi) {
         });
     };
     const openNotificationsOverlay = async (ctx) => {
-        const { GSDNotificationOverlay } = await import("../notification-overlay.js");
+        const { GSDNotificationOverlay, notificationOverlayOptions } = await import("../notification-overlay.js");
         await ctx.ui.custom((tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)), {
             overlay: true,
-            overlayOptions: {
-                width: "80%",
-                minWidth: 60,
-                maxHeight: "88%",
-                anchor: "center",
-                backdrop: true,
-            },
+            overlayOptions: notificationOverlayOptions(),
         });
     };
     const openParallelOverlay = async (ctx) => {

package/dist/resources/extensions/gsd/commands/handlers/notifications-handler.js

@@ -1,7 +1,7 @@
-// GSD Extension — /gsd notifications Command Handler
-// View, filter, and clear the persistent notification history.
+// Project/App: GSD-2
+// File Purpose: Handles /gsd notifications commands and opens the notification history overlay.
 import { readNotifications, clearNotifications, getUnreadCount, suppressPersistence, unsuppressPersistence, } from "../../notification-store.js";
-import { GSDNotificationOverlay } from "../../notification-overlay.js";
+import { GSDNotificationOverlay, notificationOverlayOptions } from "../../notification-overlay.js";
 const MAX_INLINE_ENTRIES = 40;
 function severityIcon(severity) {
     switch (severity) {
@@ -79,13 +79,7 @@ export async function handleNotificationsCommand(args, ctx, pi) {
             try {
                 const result = await ctx.ui.custom((tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)), {
                     overlay: true,
-                    overlayOptions: {
-                        width: "80%",
-                        minWidth: 60,
-                        maxHeight: "88%",
-                        anchor: "center",
-                        backdrop: true,
-                    },
+                    overlayOptions: notificationOverlayOptions(),
                 });
                 if (result !== undefined) {
                     return true;

package/dist/resources/extensions/gsd/commands/handlers/parallel.js

@@ -2,6 +2,7 @@ import { getOrchestratorState, getWorkerStatuses, isParallelActive, pauseWorker,
 import { formatEligibilityReport } from "../../parallel-eligibility.js";
 import { formatMergeResults, mergeAllCompleted, mergeCompletedMilestone } from "../../parallel-merge.js";
 import { loadEffectiveGSDPreferences, resolveParallelConfig } from "../../preferences.js";
+import { reconcileBeforeSpawn } from "../../state-reconciliation.js";
 import { projectRoot } from "../context.js";
 function emitParallelMessage(pi, content) {
     pi.sendMessage({ customType: "gsd-parallel", content, display: true });
@@ -26,6 +27,14 @@ export async function handleParallelCommand(trimmed, _ctx, pi) {
             emitParallelMessage(pi, `${report}\n\nNo milestones are eligible for parallel execution.`);
             return true;
         }
+        // ADR-017 #5707: reconcile before spawning so workers don't independently
+        // race on the same drift. Failures abort the spawn with an actionable
+        // user-visible message.
+        const gate = await reconcileBeforeSpawn(root);
+        if (!gate.ok) {
+            emitParallelMessage(pi, `${report}\n\nParallel orchestration aborted before spawn — ${gate.reason}`);
+            return true;
+        }
         const result = await startParallel(root, candidates.eligible.map((candidate) => candidate.milestoneId), loaded?.preferences);
         const lines = ["Parallel orchestration started.", `Workers: ${result.started.join(", ")}`];
         if (result.errors.length > 0) {

package/dist/resources/extensions/gsd/git-service.js

@@ -18,7 +18,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
 import { detectWorktreeName, } from "./worktree.js";
 import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, nativeHasChanges, nativeAddAllWithExclusions, nativeHasStagedChanges, nativeCommit, nativeRmCached, nativeUpdateRef, nativeAddPaths, nativeResetSoft, nativeCommitSubject, _resetHasChangesCache, } from "./native-git-bridge.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, nativeHasChanges, nativeAddAllWithExclusions, nativeHasStagedChanges, nativeCommit, nativeRmCached, nativeUpdateRef, nativeAddPaths, nativeResetSoft, nativeCommitSubject, nativeIsIgnored, _resetHasChangesCache, } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
 import { getErrorMessage } from "./error-utils.js";
 import { isInfrastructureError } from "./auto/infra-errors.js";
@@ -570,6 +570,7 @@ export class GitServiceImpl {
         const normalized = keyFiles
             .map(file => normalizeRepoRelativePath(this.basePath, file))
             .filter((file) => file !== null)
+            .filter(file => !nativeIsIgnored(this.basePath, file))
             .filter(file => !isExcludedScopedPath(file, allExclusions));
         // Drop entries that don't exist on disk. The LLM occasionally lists files
         // it intended to write but didn't (or names them with wrong casing/path).

package/dist/resources/extensions/gsd/gsd-db.js

@@ -977,32 +977,16 @@ export function setSliceSketchFlag(milestoneId, sliceId, isSketch) {
     currentDb.prepare(`UPDATE slices SET is_sketch = :is_sketch WHERE milestone_id = :mid AND id = :sid`).run({ ":is_sketch": isSketch ? 1 : 0, ":mid": milestoneId, ":sid": sliceId });
 }
 /**
- * ADR-011 auto-heal: reconcile stale is_sketch=1 rows whose PLAN already exists.
- *
- * Callers pass a predicate that resolves whether a plan file exists for a slice.
- * The predicate MUST use the canonical path resolver (`resolveSliceFile`, etc.)
- * to keep path logic in one place — do not hand-roll the path inside the callback.
- *
- * Recovers from two scenarios:
- *   1. Crash between `gsd_plan_slice` write and the sketch flag flip.
- *   2. Flag-OFF downgrade path: when `progressive_planning` is off, the dispatch
- *      rule routes sketch slices to plan-slice, which writes PLAN.md but leaves
- *      `is_sketch=1` — the next state derivation auto-heals it to 0 here.
- *
- * Not aggressive in practice: PLAN.md is only written via the DB-backed
- * `gsd_plan_slice` tool (which also inserts tasks), so a "stale PLAN.md with
- * is_sketch=1" is extremely unlikely to indicate anything other than the two
- * recovery scenarios above.
+ * ADR-017 raw primitive: returns slice IDs in a milestone whose is_sketch flag
+ * is still 1. The stale-sketch-flag drift handler at
+ * `state-reconciliation/drift/sketch-flag.ts` composes this with PLAN.md
+ * existence checks to detect drift, then writes via `setSliceSketchFlag`.
  */
-export function autoHealSketchFlags(milestoneId, hasPlanFile) {
+export function getSketchedSliceIds(milestoneId) {
     if (!currentDb)
-        return;
+        return [];
     const rows = currentDb.prepare(`SELECT id FROM slices WHERE milestone_id = :mid AND is_sketch = 1`).all({ ":mid": milestoneId });
-    for (const row of rows) {
-        if (hasPlanFile(row.id)) {
-            setSliceSketchFlag(milestoneId, row.id, false);
-        }
-    }
+    return rows.map((r) => r.id);
 }
 export function upsertSlicePlanning(milestoneId, sliceId, planning) {
     if (!currentDb)

package/dist/resources/extensions/gsd/health-widget-core.js

@@ -51,7 +51,7 @@ export function buildHealthLines(data, width) {
         return ["  GSD  No project loaded — run /gsd to start"];
     }
     if (data.projectState === "initialized") {
-        return ["  GSD  Project initialized — run /gsd to continue setup"];
+        return ["  GSD  Project Initialized"];
     }
     const leftParts = [];
     const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);

package/dist/resources/extensions/gsd/health-widget.js

@@ -1,12 +1,5 @@
-/**
- * GSD Health Widget — always-on ambient health signal rendered belowEditor.
- *
- * Shows a compact 1-2 line summary: progress score, budget, provider key
- * status, and doctor/environment issue count. Refreshes every 60 seconds.
- * Quiet when everything is healthy; turns amber/red when issues arise.
- *
- * Widget key: "gsd-health", placement: "belowEditor"
- */
+// Project/App: GSD-2
+// File Purpose: Always-on ambient health signal rendered below the editor.
 import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -14,6 +7,7 @@ import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeComm
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { projectRoot } from "./commands/context.js";
 import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
+export const HEALTH_WIDGET_ACTIVE_HINTS = "  /gsd auto to run  ·  /gsd status for overview  ·  /gsd visualize to inspect  ·  /gsd notifications for history  ·  /gsd help";
 // ── Data loader ────────────────────────────────────────────────────────────────
 function loadHealthWidgetData(basePath) {
     let budgetCeiling;
@@ -119,7 +113,7 @@ export function initHealthWidget(ctx) {
                 if (!cachedLines || cachedWidth !== width) {
                     cachedLines = buildHealthLines(data, width);
                     if (data.projectState === "active") {
-                        cachedLines = [...cachedLines, _theme.fg("dim", "  /gsd auto to run  ·  /gsd status for overview  ·  /gsd help")];
+                        cachedLines = [...cachedLines, _theme.fg("dim", HEALTH_WIDGET_ACTIVE_HINTS)];
                     }
                     cachedWidth = width;
                 }

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -734,101 +734,6 @@ export function detectStaleRenders(basePath) {
     }
     return stale;
 }
-// ─── Stale Repair ─────────────────────────────────────────────────────────
-/**
- * Repair all stale renders detected by `detectStaleRenders()`.
- *
- * For each stale entry, calls the appropriate render function:
- * - Roadmap checkbox mismatches → renderRoadmapCheckboxes()
- * - Plan checkbox mismatches → renderPlanCheckboxes()
- * - Missing task summaries → renderTaskSummary()
- * - Missing slice summaries/UATs → renderSliceSummary()
- *
- * Idempotent: calling twice with no DB changes produces zero repairs on the second call.
- *
- * @returns the number of files repaired
- */
-export async function repairStaleRenders(basePath) {
-    const staleEntries = detectStaleRenders(basePath);
-    if (staleEntries.length === 0)
-        return 0;
-    // Deduplicate: a single roadmap/plan file might appear multiple times
-    // (once per mismatched checkbox). We only need to re-render it once.
-    const repairedPaths = new Set();
-    let repairCount = 0;
-    for (const entry of staleEntries) {
-        if (repairedPaths.has(entry.path))
-            continue;
-        // Normalize path separators for cross-platform regex matching
-        const normPath = entry.path.replace(/\\/g, "/");
-        try {
-            // Determine repair action from the reason
-            if (entry.reason.includes("in roadmap")) {
-                // Roadmap checkbox mismatch — extract milestone ID from path
-                const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
-                if (milestoneMatch) {
-                    const ok = await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
-                    if (ok) {
-                        repairedPaths.add(entry.path);
-                        repairCount++;
-                    }
-                }
-            }
-            else if (entry.reason.includes("in plan")) {
-                // Plan checkbox mismatch — extract milestone + slice IDs from path
-                const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-                if (pathMatch) {
-                    const ok = await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
-                    if (ok) {
-                        repairedPaths.add(entry.path);
-                        repairCount++;
-                    }
-                }
-            }
-            else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^T\d+/)) {
-                // Missing task summary — extract IDs from path
-                const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
-                const taskMatch = entry.reason.match(/^(T\d+)/);
-                if (pathMatch && taskMatch) {
-                    const ok = await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
-                    if (ok) {
-                        repairedPaths.add(entry.path);
-                        repairCount++;
-                    }
-                }
-            }
-            else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^S\d+/)) {
-                // Missing slice summary — extract IDs from path
-                const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-                if (pathMatch) {
-                    const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-                    if (ok) {
-                        repairedPaths.add(entry.path);
-                        repairCount++;
-                    }
-                }
-            }
-            else if (entry.reason.includes("UAT.md missing")) {
-                // Missing slice UAT — renderSliceSummary handles both SUMMARY + UAT
-                const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-                if (pathMatch) {
-                    const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-                    if (ok) {
-                        repairedPaths.add(entry.path);
-                        repairCount++;
-                    }
-                }
-            }
-        }
-        catch (err) {
-            logWarning("renderer", `repair failed for ${entry.path}: ${err.message}`);
-        }
-    }
-    if (repairCount > 0) {
-        process.stderr.write(`markdown-renderer: repaired ${repairCount} stale render(s)\n`);
-    }
-    return repairCount;
-}
 export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanData) {
     const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
         ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -551,21 +551,21 @@ export function nativeAddAll(basePath) {
 export function nativeAddTracked(basePath) {
     gitFileExec(basePath, ["add", "-u"]);
 }
-function isDotGsdIgnored(basePath) {
-    for (const path of [".gsd", ".gsd/"]) {
-        try {
-            execFileSync("git", ["check-ignore", "-q", path], {
-                cwd: basePath,
-                stdio: "pipe",
-                env: GIT_NO_PROMPT_ENV,
-            });
-            return true;
-        }
-        catch {
-            // exit 1 means this form is not ignored; try the next variant
-        }
+export function nativeIsIgnored(basePath, path) {
+    try {
+        execFileSync("git", ["check-ignore", "-q", "--", path], {
+            cwd: basePath,
+            stdio: "pipe",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        return true;
+    }
+    catch {
+        return false;
     }
-    return false;
+}
+function isDotGsdIgnored(basePath) {
+    return [".gsd", ".gsd/"].some(path => nativeIsIgnored(basePath, path));
 }
 /**
  * Determine whether the project opts out of GSD-managed `.gitignore` via

package/dist/resources/extensions/gsd/notification-overlay.js

@@ -1,11 +1,25 @@
-// GSD Extension — Notification History Overlay
-// Scrollable panel showing all persisted notifications with severity filtering.
-// Toggled with Ctrl+Alt+N (⌃⌥N on macOS), Ctrl+Shift+N fallback, or /gsd notifications.
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi, matchesKey, Key } from "@gsd/pi-tui";
+// Project/App: GSD-2
+// File Purpose: Notification history overlay with severity filtering and width-safe TUI rendering.
+import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { readNotifications, markAllRead, clearNotifications, onNotificationStoreChange, } from "./notification-store.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
-import { padRight, joinColumns } from "../shared/mod.js";
-const FILTER_CYCLE = ["all", "error", "warning", "info"];
+import { padRightVisible, renderFrame, renderKeyHints, rightAlign, wrapVisibleText, } from "./tui/render-kit.js";
+const FILTER_CYCLE = ["all", "error", "warning", "success", "info"];
+const OVERLAY_WIDTH = "58%";
+const OVERLAY_MIN_WIDTH = 68;
+const OVERLAY_MAX_HEIGHT_PERCENT = 52;
+const OVERLAY_MARGIN = { top: 2, right: 2, bottom: 6, left: 2 };
+export function notificationOverlayOptions() {
+    return {
+        width: OVERLAY_WIDTH,
+        minWidth: OVERLAY_MIN_WIDTH,
+        maxHeight: `${OVERLAY_MAX_HEIGHT_PERCENT}%`,
+        anchor: "top-center",
+        row: "24%",
+        margin: OVERLAY_MARGIN,
+        backdrop: true,
+    };
+}
 function severityIcon(severity) {
     switch (severity) {
         case "error": return "✗";
@@ -15,15 +29,6 @@ function severityIcon(severity) {
         default: return "●";
     }
 }
-/** Column-aware word wrap using pi-tui's native wrapper (handles unicode/ANSI). */
-function wrapText(text, maxWidth) {
-    if (maxWidth <= 0)
-        return [text];
-    const lines = wrapTextWithAnsi(text, maxWidth);
-    // Safety clamp: if any line still exceeds maxWidth (e.g. unbreakable long token),
-    // truncate it with an ellipsis so it cannot bleed past the box border.
-    return lines.map((l) => visibleWidth(l) > maxWidth ? truncateToWidth(l, maxWidth, "…") : l);
-}
 function formatTimestamp(ts) {
     try {
         const d = new Date(ts);
@@ -155,12 +160,15 @@ export class GSDNotificationOverlay {
             return this.cachedLines;
         }
         const content = this.buildContentLines(width);
-        const maxVisibleRows = Math.max(5, process.stdout.rows ? process.stdout.rows - 8 : 24) - 2;
+        const terminalRows = process.stdout.rows || 32;
+        const availableRows = Math.max(1, terminalRows - OVERLAY_MARGIN.top - OVERLAY_MARGIN.bottom);
+        const overlayRows = Math.min(availableRows, Math.max(1, Math.floor((terminalRows * OVERLAY_MAX_HEIGHT_PERCENT) / 100)));
+        const maxVisibleRows = Math.max(5, overlayRows - 2);
         const visibleContentRows = Math.min(content.length, maxVisibleRows);
         const maxScroll = Math.max(0, content.length - visibleContentRows);
         this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
         const visibleContent = content.slice(this.scrollOffset, this.scrollOffset + visibleContentRows);
-        const lines = this.wrapInBox(visibleContent, width);
+        const lines = renderFrame(this.theme, visibleContent, width);
         this.cachedWidth = width;
         this.cachedLines = lines;
         return lines;
@@ -192,30 +200,14 @@ export class GSDNotificationOverlay {
             this.tui.requestRender();
         }
     }
-    wrapInBox(inner, width) {
-        const th = this.theme;
-        const border = (s) => th.fg("borderAccent", s);
-        const innerWidth = width - 4;
-        const lines = [];
-        lines.push(border("╭" + "─".repeat(width - 2) + "╮"));
-        for (const line of inner) {
-            const truncated = truncateToWidth(line, innerWidth);
-            const padWidth = Math.max(0, innerWidth - visibleWidth(truncated));
-            lines.push(border("│") + " " + truncated + " ".repeat(padWidth) + " " + border("│"));
-        }
-        lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
-        return lines;
-    }
     buildContentLines(width) {
         const th = this.theme;
-        const shellWidth = width - 4;
-        const contentWidth = Math.min(shellWidth, 128);
-        const sidePad = Math.max(0, Math.floor((shellWidth - contentWidth) / 2));
-        const leftMargin = " ".repeat(sidePad);
+        const shellWidth = Math.max(1, width - 4);
+        const contentWidth = shellWidth;
         const lines = [];
         const row = (content = "") => {
             const truncated = truncateToWidth(content, contentWidth);
-            return leftMargin + padRight(truncated, contentWidth);
+            return padRightVisible(truncated, contentWidth);
         };
         const blank = () => row("");
         const hr = () => row(th.fg("dim", "─".repeat(contentWidth)));
@@ -223,13 +215,16 @@ export class GSDNotificationOverlay {
         const title = th.fg("accent", th.bold("Notifications"));
         const filterLabel = this.filter === "all"
             ? th.fg("dim", "all")
-            : th.fg(this.filter === "error" ? "error" : this.filter === "warning" ? "warning" : "dim", this.filter);
+            : th.fg(this.filter === "error" ? "error"
+                : this.filter === "warning" ? "warning"
+                    : this.filter === "success" ? "success"
+                        : "dim", this.filter);
         const count = `${this.filteredEntries.length} entries`;
-        lines.push(row(joinColumns(`${title}  ${th.fg("dim", "filter:")} ${filterLabel}`, th.fg("dim", count), contentWidth)));
+        lines.push(row(rightAlign(`${title}  ${th.fg("dim", "filter:")} ${filterLabel}`, th.fg("dim", count), contentWidth)));
         lines.push(hr());
         // Controls
         const closeShortcut = formattedShortcutPair("notifications");
-        lines.push(row(th.fg("dim", `↑/↓ scroll  f filter  c clear  Esc close  (${closeShortcut})`)));
+        lines.push(row(renderKeyHints(th, ["↑/↓ scroll", "f filter", "c clear", `Esc/${closeShortcut} close`], contentWidth)));
         lines.push(blank());
         // Entries
         const filtered = this.filteredEntries;
@@ -254,7 +249,7 @@ export class GSDNotificationOverlay {
             const prefixWidth = visibleWidth(prefix);
             const msgMaxWidth = Math.max(10, contentWidth - prefixWidth);
             // Wrap long messages onto continuation lines indented to align with message start
-            const msgLines = wrapText(entry.message, msgMaxWidth);
+            const msgLines = wrapVisibleText(entry.message, msgMaxWidth);
             const indent = " ".repeat(prefixWidth);
             for (let i = 0; i < msgLines.length; i++) {
                 if (i === 0) {

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -7,9 +7,10 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { loadFile } from "./files.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
-import { mergeMilestoneToMain } from "./auto-worktree.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
+import { buildWorktreeLifecycleDeps } from "./auto.js";
+import { mergeMilestoneStandalone, } from "./worktree-lifecycle.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -105,37 +106,42 @@ export function determineMergeOrder(workers, order = "sequential", basePath) {
 }
 /**
  * Attempt to merge a single milestone's worktree back to main.
- * Wraps mergeMilestoneToMain with error handling for parallel context.
+ *
+ * Routes through `WorktreeLifecycle.mergeMilestoneStandalone` so parallel
+ * callers get the same projection-finalize / roadmap-fallback / secondary-
+ * teardown invariants as the single-loop path. Closes the parallel-merge
+ * bypass that ADR-016 names (issue #5618).
  */
 export async function mergeCompletedMilestone(basePath, milestoneId) {
+    // Resolve the worktree path explicitly; parallel-merge has no AutoSession
+    // to read it from. Only use the worktree path when git actually knows
+    // about it (`getAutoWorktreePath` returns non-null). When the directory
+    // exists on disk but isn't a registered git worktree (e.g. a stale
+    // session-status marker dir), fall back to the project root and let the
+    // standalone's mode detection pick branch-mode or skipped — using the
+    // un-registered dir as `worktreeBasePath` would cause `getCurrentBranch`
+    // to fail with a "Worktree HEAD diverged" error.
+    const registeredWtPath = getAutoWorktreePath(basePath, milestoneId);
+    const worktreeBasePath = registeredWtPath ?? basePath;
+    let result;
     try {
-        // Load the roadmap content (needed by mergeMilestoneToMain)
-        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-        if (!roadmapPath) {
-            return {
-                milestoneId,
-                success: false,
-                error: `No roadmap found for ${milestoneId}`,
-            };
-        }
-        const roadmapContent = await loadFile(roadmapPath);
-        if (!roadmapContent) {
-            return {
-                milestoneId,
-                success: false,
-                error: `Could not read roadmap for ${milestoneId}`,
-            };
-        }
-        // Attempt the merge
-        const result = mergeMilestoneToMain(basePath, milestoneId, roadmapContent);
-        // Clean up parallel session status
-        removeSessionStatus(basePath, milestoneId);
-        return {
+        result = mergeMilestoneStandalone(buildWorktreeLifecycleDeps(), {
+            originalBasePath: basePath,
+            worktreeBasePath,
             milestoneId,
-            success: true,
-            commitMessage: result.commitMessage,
-            pushed: result.pushed,
-        };
+            // Parallel context never runs with degraded isolation — workers only
+            // exist when isolation succeeded. Pass `false` explicitly so the
+            // standalone's degraded-skip branch is not reached.
+            isolationDegraded: false,
+            notify: (msg, level) => {
+                // Surface user-visible messages from the standalone through the
+                // workflow logger so the parallel merge's progress is visible in
+                // the same channel as the rest of the parallel orchestration.
+                if (level === "error" || level === "warning") {
+                    logWarning("parallel", `${milestoneId}: ${msg}`);
+                }
+            },
+        });
     }
     catch (err) {
         if (err instanceof MergeConflictError) {
@@ -152,6 +158,23 @@ export async function mergeCompletedMilestone(basePath, milestoneId) {
             error: getErrorMessage(err),
         };
     }
+    if (!result.merged) {
+        return {
+            milestoneId,
+            success: false,
+            error: result.mode === "skipped"
+                ? `Merge skipped for ${milestoneId} (mode=none or isolation degraded).`
+                : `No roadmap for ${milestoneId} — milestone branch preserved for manual merge.`,
+        };
+    }
+    // Clean up parallel session status — only on a real merge.
+    removeSessionStatus(basePath, milestoneId);
+    return {
+        milestoneId,
+        success: true,
+        commitMessage: result.commitMessage,
+        pushed: result.pushed,
+    };
 }
 /**
  * Merge all completed milestones in sequence.