@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -8,12 +8,12 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, } from "./gsd-db.js";
 import { closeWorkflowDatabase, getWorkflowDatabasePath, openWorkflowDatabasePath, } from "./db-workspace.js";
 import { execFileSync } from "node:child_process";
-import { gsdRoot, resolveGsdPathContract } from "./paths.js";
+import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveGsdPathContract, resolveMilestonePath, } from "./paths.js";
 import { createWorktree, removeWorktree, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { worktreePathFor } from "./worktree-placement.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
@@ -310,9 +310,24 @@ export const SAFE_AUTO_RESOLVE_PATTERNS = [
     /\/__pycache__\//,
     /\.DS_Store$/,
     /\.map$/,
+    // Regenerable dependency lockfiles. These are fully derivable from their
+    // manifests by the package manager, so accepting the merge side during
+    // auto-resolve clears the conflict markers without losing meaningful edits —
+    // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
+    /(?:^|\/)pnpm-lock\.yaml$/,
+    /(?:^|\/)package-lock\.json$/,
+    /(?:^|\/)npm-shrinkwrap\.json$/,
+    /(?:^|\/)yarn\.lock$/,
+    /(?:^|\/)bun\.lockb?$/,
+    /(?:^|\/)Cargo\.lock$/,
+    /(?:^|\/)composer\.lock$/,
+    /(?:^|\/)Gemfile\.lock$/,
+    /(?:^|\/)Pipfile\.lock$/,
+    /(?:^|\/)poetry\.lock$/,
 ];
 /** Returns true if the file path is safe to auto-resolve during merge.
- * Covers `.gsd/` state files and common build artifacts. */
+ * Covers `.gsd/` state files, common build artifacts, and regenerable
+ * dependency lockfiles. */
 export const isSafeToAutoResolve = (filePath) => filePath.startsWith(".gsd/") ||
     SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
 // ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
@@ -559,99 +574,102 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
             }
         }
     }
-    // Sync milestones: copy entire milestone directories that are missing
-    const mainMilestonesDir = join(mainGsd, "milestones");
-    const wtMilestonesDir = join(wtGsd, "milestones");
-    if (existsSync(mainMilestonesDir)) {
-        try {
-            mkdirSync(wtMilestonesDir, { recursive: true });
-            const mainMilestones = readdirSync(mainMilestonesDir, {
-                withFileTypes: true,
-            })
-                .filter((d) => d.isDirectory())
-                .map((d) => d.name);
-            for (const mid of mainMilestones) {
-                const srcDir = join(mainMilestonesDir, mid);
-                const dstDir = join(wtMilestonesDir, mid);
-                if (!existsSync(dstDir)) {
-                    // Entire milestone missing from worktree — copy it
-                    try {
-                        cpSync(srcDir, dstDir, { recursive: true });
-                        synced.push(`milestones/${mid}/`);
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+    // Sync milestone/phase trees: copy entire directories that are missing.
+    // Support both flat-phase (phases/) and legacy (milestones/) layouts.
+    for (const layoutSegment of ["phases", "milestones"]) {
+        const mainMilestonesDir = join(mainGsd, layoutSegment);
+        const wtMilestonesDir = join(wtGsd, layoutSegment);
+        if (existsSync(mainMilestonesDir)) {
+            try {
+                mkdirSync(wtMilestonesDir, { recursive: true });
+                const mainMilestones = readdirSync(mainMilestonesDir, {
+                    withFileTypes: true,
+                })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => d.name);
+                for (const mid of mainMilestones) {
+                    const srcDir = join(mainMilestonesDir, mid);
+                    const dstDir = join(wtMilestonesDir, mid);
+                    if (!existsSync(dstDir)) {
+                        // Entire milestone missing from worktree — copy it
+                        try {
+                            cpSync(srcDir, dstDir, { recursive: true });
+                            synced.push(`milestones/${mid}/`);
+                        }
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
-                }
-                else {
-                    // Milestone directory exists but may be missing files (stale snapshot).
-                    // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
-                    try {
-                        const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
-                        for (const f of srcFiles) {
-                            const srcFile = join(srcDir, f);
-                            const dstFile = join(dstDir, f);
-                            if (!existsSync(dstFile)) {
-                                try {
-                                    const srcStat = lstatSyncFn(srcFile);
-                                    if (srcStat.isFile()) {
-                                        cpSync(srcFile, dstFile);
-                                        synced.push(`milestones/${mid}/${f}`);
+                    else {
+                        // Milestone directory exists but may be missing files (stale snapshot).
+                        // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+                        try {
+                            const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
+                            for (const f of srcFiles) {
+                                const srcFile = join(srcDir, f);
+                                const dstFile = join(dstDir, f);
+                                if (!existsSync(dstFile)) {
+                                    try {
+                                        const srcStat = lstatSyncFn(srcFile);
+                                        if (srcStat.isFile()) {
+                                            cpSync(srcFile, dstFile);
+                                            synced.push(`milestones/${mid}/${f}`);
+                                        }
+                                    }
+                                    catch (err) {
+                                        /* non-fatal */
+                                        logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
                                     }
                                 }
+                            }
+                            // Sync slices directory if it exists in main but not in worktree
+                            const srcSlicesDir = join(srcDir, "slices");
+                            const dstSlicesDir = join(dstDir, "slices");
+                            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+                                try {
+                                    cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                                    synced.push(`milestones/${mid}/slices/`);
+                                }
                                 catch (err) {
                                     /* non-fatal */
-                                    logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
+                                    logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
                                 }
                             }
-                        }
-                        // Sync slices directory if it exists in main but not in worktree
-                        const srcSlicesDir = join(srcDir, "slices");
-                        const dstSlicesDir = join(dstDir, "slices");
-                        if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
-                            try {
-                                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
-                                synced.push(`milestones/${mid}/slices/`);
-                            }
-                            catch (err) {
-                                /* non-fatal */
-                                logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-                            }
-                        }
-                        else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
-                            // Both exist — sync missing slice directories
-                            const srcSlices = readdirSync(srcSlicesDir, {
-                                withFileTypes: true,
-                            })
-                                .filter((d) => d.isDirectory())
-                                .map((d) => d.name);
-                            for (const sid of srcSlices) {
-                                const srcSlice = join(srcSlicesDir, sid);
-                                const dstSlice = join(dstSlicesDir, sid);
-                                if (!existsSync(dstSlice)) {
-                                    try {
-                                        cpSync(srcSlice, dstSlice, { recursive: true });
-                                        synced.push(`milestones/${mid}/slices/${sid}/`);
-                                    }
-                                    catch (err) {
-                                        /* non-fatal */
-                                        logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                            else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+                                // Both exist — sync missing slice directories
+                                const srcSlices = readdirSync(srcSlicesDir, {
+                                    withFileTypes: true,
+                                })
+                                    .filter((d) => d.isDirectory())
+                                    .map((d) => d.name);
+                                for (const sid of srcSlices) {
+                                    const srcSlice = join(srcSlicesDir, sid);
+                                    const dstSlice = join(dstSlicesDir, sid);
+                                    if (!existsSync(dstSlice)) {
+                                        try {
+                                            cpSync(srcSlice, dstSlice, { recursive: true });
+                                            synced.push(`milestones/${mid}/slices/${sid}/`);
+                                        }
+                                        catch (err) {
+                                            /* non-fatal */
+                                            logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                                        }
                                     }
                                 }
                             }
                         }
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
                 }
             }
-        }
-        catch (err) {
-            /* non-fatal */
-            logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            catch (err) {
+                /* non-fatal */
+                logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return { synced };
@@ -968,10 +986,10 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false, preserveWorktree = false } = opts;
     const previousCwd = safeCwd(originalBasePath);
+    let clearActiveWorkspace = true;
     // Wrap the entire teardown body in a single try/finally so activeWorkspace
-    // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
-    // was deleted before teardown ran). Previously the finally only covered
-    // removeWorktree, leaving the registry stale on a chdir failure (H3 fix).
+    // is cleared on completion or irrecoverable failure — even if process.chdir
+    // throws (e.g. originalBasePath was deleted before teardown ran).
     try {
         try {
             process.chdir(originalBasePath);
@@ -1008,17 +1026,23 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
         // 3. Remove the worktree unless this exit path explicitly preserves it
         //    (slice-parallel dispatch stops the parent loop but keeps the parent
         //    milestone worktree for restart/re-entry).
+        let worktreeRemoved = preserveWorktree;
         if (!preserveWorktree) {
-            removeWorktree(originalBasePath, milestoneId, {
+            worktreeRemoved = removeWorktree(originalBasePath, milestoneId, {
                 branch,
                 deleteBranch: !preserveBranch,
             });
+            if (!worktreeRemoved) {
+                logWarning("worktree", `Worktree removal aborted for ${milestoneId}; uncommitted work was preserved. ` +
+                    `Manual quarantine recovery may be needed before retrying teardown.`, { worktree: milestoneId });
+                clearActiveWorkspace = false;
+            }
         }
         // Verify cleanup succeeded — warn if the worktree directory is still on disk.
         // On Windows, bash-based cleanup can silently fail when paths contain
         // backslashes (#1436), leaving ~1 GB+ orphaned directories.
         const wtDir = worktreePath(originalBasePath, milestoneId);
-        if (!preserveWorktree && existsSync(wtDir)) {
+        if (!preserveWorktree && worktreeRemoved && existsSync(wtDir)) {
             logWarning("reconcile", `Worktree directory still exists after teardown: ${wtDir}. ` +
                 `This is likely an orphaned directory consuming disk space. ` +
                 `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId });
@@ -1039,10 +1063,12 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
         }
     }
     finally {
-        // Clear module state unconditionally — regardless of which step above
-        // failed. A stale activeWorkspace causes getActiveAutoWorktreeContext()
-        // to return wrong data for subsequent operations.
-        setActiveWorkspace(null);
+        // Clear module state when teardown completed or failed irrecoverably.
+        // When removeWorktree returns false (quarantine failure), preserve the
+        // registry so recovery logic still sees the active milestone worktree.
+        if (clearActiveWorkspace) {
+            setActiveWorkspace(null);
+        }
     }
 }
 /**
@@ -1473,15 +1499,28 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         catch (err) {
             logWarning("worktree", `clearProjectRootStateFiles failed during already-merged cleanup: ${err instanceof Error ? err.message : String(err)}`);
         }
+        let worktreeRemoved = true;
         try {
-            removeWorktree(originalBasePath_, milestoneId, {
+            worktreeRemoved = removeWorktree(originalBasePath_, milestoneId, {
                 branch: milestoneBranch,
                 deleteBranch: false,
             });
         }
         catch (err) {
+            worktreeRemoved = false;
             logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        if (!worktreeRemoved) {
+            logWarning("worktree", `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`);
+            nudgeGitBranchCache(previousCwd);
+            try {
+                process.chdir(originalBasePath_);
+            }
+            catch (err) {
+                logWarning("worktree", `chdir to project root after already-merged cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+        }
         try {
             nativeBranchDelete(originalBasePath_, milestoneBranch);
         }
@@ -1507,10 +1546,18 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
     // does not sweep queued CONTEXT files into the stash. If stash pop later
     // fails, files trapped inside the stash are permanently lost (#2505).
-    const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
+    const planningDir = milestonesDir(originalBasePath_);
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
     let shelterRestored = false;
+    const mergeDirNames = new Set([milestoneId]);
+    const resolvedMergeDir = resolveMilestonePath(originalBasePath_, milestoneId);
+    if (resolvedMergeDir) {
+        mergeDirNames.add(basename(resolvedMergeDir));
+    }
+    else {
+        mergeDirNames.add(canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+    }
     // Helper: restore sheltered milestone directories (#2505).
     // Called on both success and error paths to ensure queued CONTEXT files
     // are never permanently lost. Idempotent — the error path may fire after
@@ -1535,11 +1582,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 continue;
             }
             try {
-                mkdirSync(milestonesDir, { recursive: true });
+                mkdirSync(planningDir, { recursive: true });
                 // Test seam: when _restoreEntryFn is injected, route the copy through it
                 // so the best-effort failure path (and shelter-retention guarantee) can
                 // be exercised deterministically. Production leaves it null → real cpSync.
-                const dest = join(milestonesDir, dirName);
+                const dest = join(planningDir, dirName);
                 if (_restoreEntryFn) {
                     _restoreEntryFn(src, dest);
                 }
@@ -1569,15 +1616,15 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
     };
     try {
-        if (existsSync(milestonesDir)) {
-            const entries = readdirSync(milestonesDir, { withFileTypes: true });
+        if (existsSync(planningDir)) {
+            const entries = readdirSync(planningDir, { withFileTypes: true });
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
                 // Only shelter directories that do NOT belong to the milestone being merged
-                if (entry.name === milestoneId)
+                if (mergeDirNames.has(entry.name))
                     continue;
-                const srcDir = join(milestonesDir, entry.name);
+                const srcDir = join(planningDir, entry.name);
                 const dstDir = join(shelterDir, entry.name);
                 try {
                     mkdirSync(shelterDir, { recursive: true });
@@ -1602,8 +1649,8 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //     branch. Passing NO pathspec lets git skip gitignored paths silently;
     //     adding an explicit pathspec trips a `git add`-style fatal on ignored
     //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
-    //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
-    //     in step 7 above, so they won't be swept into the stash.
+    //     Queued CONTEXT files under `.gsd/phases/*` (or legacy milestones/*)
+    //     are already sheltered in step 7 above, so they won't be swept into the stash.
     // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
     // sidecars while the connection is open. `git stash --include-untracked`
     // walks those files and fails with EBUSY (#4704). Close the DB before
@@ -1906,16 +1953,22 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     }
     const finalizeMilestoneCleanup = () => {
         // 12. Remove worktree directory first (must happen before branch deletion)
+        let worktreeRemoved = true;
         try {
-            removeWorktree(originalBasePath_, milestoneId, {
+            worktreeRemoved = removeWorktree(originalBasePath_, milestoneId, {
                 branch: milestoneBranch,
                 deleteBranch: false,
             });
         }
         catch (err) {
+            worktreeRemoved = false;
             // Best-effort -- worktree dir may already be gone
             logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        if (!worktreeRemoved) {
+            logWarning("worktree", `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`);
+            return;
+        }
         // 13. Delete milestone branch (after worktree removal so ref is unlocked)
         try {
             nativeBranchDelete(originalBasePath_, milestoneBranch);

package/dist/resources/extensions/gsd/auto.js

@@ -19,7 +19,7 @@ import { setRuntimeKv, deleteRuntimeKv, } from "./db/runtime-kv.js";
 import { extractSection, getManifestStatus, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
-import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, canonicalPhaseDirName, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, readActiveMilestoneId, } from "./session-forensics.js";
@@ -27,7 +27,7 @@ import { writeLock, clearLock, clearStaleWorkerLock, readCrashLock, isLockProces
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, loadEffectiveGSDPreferencesWithRegistry, resolveProfileAnchorProvider, getIsolationMode, resolveEffectiveUnitIsolationMode, } from "./preferences.js";
 import { playNotificationBell, sendDesktopNotification } from "./notifications.js";
-import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, HARD_CONTEXT_REROOT_THRESHOLD_PERCENT, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, isToolInvocationError, isQueuedUserMessageSkip, isDeterministicPolicyError, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { selectAndApplyModel, resolveModelId, clearToolBaseline } from "./auto-model-selection.js";
@@ -68,7 +68,7 @@ import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { updateProgressWidget as _updateProgressWidget, setCompletionProgressWidget, setAutoOutcomeWidget, setAutoActiveStatus, updateSliceProgressCache, clearSliceProgressCache, unitVerb, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone, getMilestoneSlices, } from "./gsd-db.js";
-import { closeWorkflowDatabase } from "./db-workspace.js";
+import { checkpointWorkflowDatabase, closeWorkflowDatabase } from "./db-workspace.js";
 import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
 import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
@@ -369,7 +369,7 @@ function getEffectiveUnitIsolationMode(basePath) {
  * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
  */
 // Re-export budget utilities for external consumers
-export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 function closeOutSignalInterruptedUnit(currentBasePath) {
     const currentUnit = s.currentUnit;
     if (!currentUnit)
@@ -651,6 +651,11 @@ export function stopAutoRemote(projectRoot) {
  * The normal stop path stays SIGTERM-only so cooperative sessions can clean up;
  * this path is only for the explicit "Force start" action.
  */
+// Grace window between SIGTERM and SIGKILL so the target can run its cleanup
+// handler (lock release, DB snapshot flush, worktree teardown). Polled so a
+// process that exits early is not made to wait the full window.
+const FORCE_STOP_GRACE_MS = 3000;
+const FORCE_STOP_POLL_MS = 100;
 export function forceStopAutoRemote(projectRoot) {
     const lock = readCrashLock(projectRoot);
     if (!lock)
@@ -665,6 +670,14 @@ export function forceStopAutoRemote(projectRoot) {
     }
     try {
         process.kill(lock.pid, "SIGTERM");
+        // Poll for graceful exit before escalating. Synchronous sleep keeps this
+        // function sync for its callers (Atomics.wait times out with no notify).
+        const deadline = Date.now() + FORCE_STOP_GRACE_MS;
+        while (Date.now() < deadline) {
+            if (!isLockProcessAlive(lock))
+                break;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, FORCE_STOP_POLL_MS);
+        }
         if (isLockProcessAlive(lock)) {
             process.kill(lock.pid, "SIGKILL");
         }
@@ -904,9 +917,10 @@ export async function rerootCommandSession(cmdCtx, workspaceRoot) {
     }
 }
 /**
- * After a completed step-mode unit, reclaim context headroom when usage is at
- * or above the compaction threshold. Writes a context-mode snapshot first, then
- * re-roots the visible command session while leaving the NEXT progress surface.
+ * After a completed step-mode unit, warn when usage reaches the configurable
+ * soft context threshold. At the fixed hard boundary, write a context-mode
+ * snapshot and re-root the visible command session while leaving the NEXT
+ * progress surface.
  */
 export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, cmdCtx, originalBasePath) {
     if (!cmdCtx)
@@ -915,18 +929,24 @@ export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, c
     const { loadEffectiveGSDPreferences } = await import("./preferences.js");
     const prefs = loadEffectiveGSDPreferences(workspaceRoot);
     const compactionThreshold = prefs?.preferences.context_management?.compaction_threshold_percent;
-    if (!shouldRerootStepSessionForContext(contextPercent, compactionThreshold)) {
+    const shouldWarn = shouldWarnStepSessionForContext(contextPercent, compactionThreshold);
+    const shouldReroot = shouldRerootStepSessionForContext(contextPercent);
+    if (!shouldWarn && !shouldReroot) {
+        return { rerooted: false };
+    }
+    const displayPercent = contextPercent.toFixed(1);
+    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
+    if (!shouldReroot) {
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (soft threshold: ${thresholdDisplay}%). Use /compact when convenient; continuing in this session is still safe.`, "info");
         return { rerooted: false };
     }
     const { resolveWorktreeProjectRoot } = await import("./worktree-root.js");
     const snapshotBase = resolveWorktreeProjectRoot(workspaceRoot, originalBasePath);
     const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
     await writeContextModeCompactionSnapshot(snapshotBase);
-    const displayPercent = contextPercent.toFixed(1);
-    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
     const result = await rerootCommandSession(cmdCtx, workspaceRoot);
     if (result.status === "ok") {
-        ctx.ui.notify(`Step complete — context at ${displayPercent}% (threshold: ${thresholdDisplay}%). Fresh session ready for /gsd next.`, "info");
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`, "info");
         return { rerooted: true };
     }
     if (result.status === "cancelled") {
@@ -1082,6 +1102,12 @@ export async function stopAuto(ctx, pi, reason, options = {}) {
     const installTerminalCloseoutOutcome = completionStopRequested && preserveCloseoutTranscript;
     const preserveCompletionSurface = completionStopRequested || preserveCloseoutTranscript;
     s.completionStopInProgress = preserveCompletionSurface;
+    try {
+        checkpointWorkflowDatabase();
+    }
+    catch (e) {
+        debugLog("stop-checkpoint-failed", { error: e instanceof Error ? e.message : String(e) });
+    }
     playNotificationBell("stop", loadedPreferences?.notifications);
     // #4764 — telemetry: record the exit reason, isolation mode, whether an auto
     // worktree was active, and whether the current milestone was merged before
@@ -1545,7 +1571,7 @@ export function _selectStopAutoWorktreeExit(args) {
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
- * from disk state. Called when the user presses Escape during auto-mode.
+ * from disk state. Called when the user presses Escape or runs `/gsd pause`.
  */
 export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     if (!s.active)
@@ -1564,6 +1590,8 @@ export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     ].filter((path) => Boolean(path)));
     s.active = false;
     s.paused = true;
+    if (options.abortActiveTurn && ctx && !ctx.isIdle())
+        ctx.abort();
     clearUnitTimeout();
     stopAutoCommandPolling();
     // Flush queued follow-up messages (#3512).
@@ -1710,7 +1738,7 @@ export function buildWorktreeLifecycleDeps() {
     //   C4 (#5627) — GitServiceImpl constructor → gitServiceFactory
     //
     // Final WorktreeLifecycleDeps shape: 3 fields (gitServiceFactory,
-    // worktreeProjection, mergeMilestoneToMain transaction runner). Down from 18 at slice-7
+    // worktreeProjection, mergeMilestone transaction runner). Down from 18 at slice-7
     // closure.
     return {
         gitServiceFactory: (basePath) => {
@@ -1718,7 +1746,7 @@ export function buildWorktreeLifecycleDeps() {
             return new GitServiceImpl(basePath, gitConfig);
         },
         worktreeProjection: new WorktreeStateProjection(),
-        mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
+        mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
     };
 }
 function buildLifecycle() {
@@ -1761,6 +1789,7 @@ function buildLoopDeps(pi, ctx) {
         stopAuto,
         pauseAuto,
         clearUnitTimeout,
+        checkpointWorkflowDatabase,
         updateProgressWidget,
         ...cmux,
         handleLostSessionLock: (ctx, lockStatus) => {
@@ -1771,7 +1800,7 @@ function buildLoopDeps(pi, ctx) {
         invalidateAllCaches,
         deriveState,
         rebuildState,
-        loadEffectiveGSDPreferences: () => loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, s.basePath || undefined, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider)),
+        loadEffectiveGSDPreferences: () => loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, s.basePath || undefined, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider), s.autoModeStartModel ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` : undefined),
         // Pre-dispatch health gate
         preDispatchHealthGate,
         // Worktree state projection (ADR-016 — single Module Interface)
@@ -1899,7 +1928,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // resume paths (#4416). The matching call in auto-start.ts covers the
     // bootstrap-only path; this call ensures the resume path is also protected.
     if (recoverFailedMigration(base)) {
-        ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
+        ctx.ui.notify("Recovered unfinished external state migration.", "info");
     }
     const unmergedStartMessage = await getUnmergedMilestoneBlockMessageForBase(base, "auto");
     if (unmergedStartMessage) {
@@ -2292,10 +2321,26 @@ export function ensurePreconditions(unitType, unitId, base, state) {
                 return;
             }
         }
-        const newDir = join(milestonesDir(base), mid);
-        mkdirSync(join(newDir, "slices"), { recursive: true });
+        // Layout-aware: if the legacy milestones/ dir exists, place the new milestone dir
+        // there (preserves the existing project layout). Otherwise use flat-phase phases/.
+        const legacyBase = legacyMilestonesDir(base);
+        const isLegacyLayout = isLegacyMilestonesLayout(base);
+        const targetBase = isLegacyLayout ? legacyBase : milestonesDir(base);
+        // Flat-phase: look up the milestone title to build the canonical NN-slug dir name
+        // (e.g. "01-foundation") that resolveMilestonePath will later find by prefix.
+        // Legacy layout keeps the raw milestone id (e.g. "M001").
+        const dirName = isLegacyLayout
+            ? mid
+            : canonicalPhaseDirName(mid, getMilestone(mid)?.title);
+        const newDir = join(targetBase, dirName);
+        // Legacy projects use a slices/ subdir; flat-phase uses top-level plan files (no slices/).
+        mkdirSync(isLegacyLayout ? join(newDir, "slices") : newDir, { recursive: true });
     }
     if (sid !== undefined) {
+        const isLegacyLayout = isLegacyMilestonesLayout(base);
+        // Flat-phase: tasks are checkboxes in NN-MM-PLAN.md — no slices/ subdir needed.
+        if (!isLegacyLayout)
+            return;
         const mDirResolved = resolveMilestonePath(base, mid);
         if (mDirResolved) {
             const slicesDir = join(mDirResolved, "slices");