gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2d3fd6e71

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

@@ -7,13 +7,12 @@
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, statSync, lstatSync as lstatSyncFn, } from "node:fs";
 import { isAbsolute, join, sep as pathSep } from "node:path";
-import { homedir } from "node:os";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, closeDatabase, openDatabase, getDbPath, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveGsdPathContract } from "./paths.js";
 import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
@@ -21,15 +20,23 @@ import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } fr
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, } from "./native-git-bridge.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "./gsd-home.js";
+import { createWorkspace } from "./workspace.js";
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
+const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
+    "workflow-preferences-WORKFLOW-PREFS.json",
+    "discuss-project-PROJECT.json",
+    "discuss-requirements-REQUIREMENTS.json",
+    "research-decision-RESEARCH-DECISION.json",
+    "research-project-RESEARCH-PROJECT.json",
+]);
 // ─── Shared Constants & Helpers ─────────────────────────────────────────────
 /**
- * Root-level .gsd/ state files synced between worktree and project root.
- * Single source of truth — used by syncGsdStateToWorktree, syncWorktreeStateBack,
- * and the dispatch-level sync functions.
+ * Root-level .gsd/ projections copied from project root into worktrees for
+ * compatibility. Project root remains the canonical state/projection root.
  */
 const ROOT_STATE_FILES = [
     "DECISIONS.md",
@@ -46,6 +53,10 @@ const ROOT_STATE_FILES = [
     // Back-sync (worktree → main) must NEVER overwrite the project root's copy
     // because the project root is authoritative for preferences (#2684).
 ];
+const ROOT_DIAGNOSTIC_FILES = [
+    "completed-units.json",
+    "metrics.json",
+];
 /**
  * Pop a stash entry by tracking the unique marker embedded in its message so
  * concurrent stash operations against the same project root cannot cause us to
@@ -130,7 +141,7 @@ const VERDICT_RE = /verdict:\s*[\w-]+/i;
  * destination when the source copy contains a `verdict:` field.
  *
  * This is the targeted fix for the UAT stuck-loop (#2821): the main
- * safeCopyRecursive uses force:false to protect worktree-authoritative
+ * safeCopyRecursive uses force:false to protect worktree-local projection
  * files (#1886), but ASSESSMENT files written by run-uat must be
  * forward-synced when the project root has a verdict. Without this,
  * the worktree retains a stale FAIL or missing ASSESSMENT and
@@ -185,8 +196,14 @@ function forceOverwriteAssessmentsWithVerdict(srcMilestoneDir, dstMilestoneDir)
     }
 }
 // ─── Module State ──────────────────────────────────────────────────────────
-/** Original project root before chdir into auto-worktree. */
-let originalBase = null;
+/** Active workspace registry — replaces the legacy `originalBase` singleton. */
+let activeWorkspace = null;
+function setActiveWorkspace(ws) {
+    activeWorkspace = ws;
+}
+function getActiveWorkspace() {
+    return activeWorkspace;
+}
 function clearProjectRootStateFiles(basePath, milestoneId) {
     const gsdDir = gsdRoot(basePath);
     const transientFiles = [
@@ -205,9 +222,9 @@ function clearProjectRootStateFiles(basePath, milestoneId) {
             }
         }
     }
-    // Clean up entire synced milestone directory and runtime/units.
-    // syncStateToProjectRoot() copies these into the project root during
-    // execution.  If they remain as untracked files when we attempt
+    // Clean up legacy synced milestone directories and runtime/units.
+    // Older versions copied these into the project root during execution.
+    // If they remain as untracked files when we attempt
     // `git merge --squash`, git rejects the merge with "local changes would
     // be overwritten", causing silent data loss (#1738).
     const syncedDirs = [
@@ -265,13 +282,41 @@ export const isSafeToAutoResolve = (filePath) => filePath.startsWith(".gsd/") ||
  * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
  * Non-fatal — sync failure should never block dispatch.
  */
+/**
+ * Scope-typed variant of syncProjectRootToWorktree.
+ *
+ * Takes an explicit (rootScope, worktreeScope) pair where rootScope is the
+ * project root and worktreeScope is the auto-worktree. Direction is encoded
+ * in argument order. Asserts both scopes belong to the same workspace identity
+ * to prevent silent mismatch bugs.
+ */
+export function syncProjectRootToWorktreeByScope(rootScope, worktreeScope) {
+    if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
+        throw new Error(`syncProjectRootToWorktreeByScope: scope identity mismatch — ` +
+            `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
+            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`);
+    }
+    if (rootScope.milestoneId !== worktreeScope.milestoneId) {
+        throw new Error(`syncProjectRootToWorktreeByScope: milestoneId mismatch — ` +
+            `rootScope.milestoneId="${rootScope.milestoneId}" worktreeScope.milestoneId="${worktreeScope.milestoneId}"`);
+    }
+    const projectRoot = rootScope.workspace.projectRoot;
+    const worktreePath_ = worktreeScope.workspace.worktreeRoot ?? worktreeScope.workspace.projectRoot;
+    const milestoneId = rootScope.milestoneId;
+    syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId);
+}
+/**
+ * @deprecated Use syncProjectRootToWorktreeByScope instead.
+ * TODO(C-future): remove once all callers migrated.
+ */
 export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId) {
     if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
         return;
     if (!milestoneId)
         return;
-    const prGsd = join(projectRoot, ".gsd");
-    const wtGsd = join(worktreePath_, ".gsd");
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const prGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
     // When .gsd is a symlink to the same external directory in both locations,
     // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
     // Compare realpaths and skip when they resolve to the same physical path (#2184).
@@ -279,12 +324,12 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
         return;
     // Copy milestone directory from project root to worktree — additive only.
     // force:false prevents cpSync from overwriting existing worktree files.
-    // Without this, worktree-authoritative files (e.g. VALIDATION.md written
+    // Without this, worktree-local files (e.g. VALIDATION.md written
     // by validate-milestone) get clobbered by stale project root copies,
     // causing an infinite re-validation loop (#1886).
     safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId), { force: false });
     // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
-    // The additive-only copy above preserves worktree-authoritative files, but
+    // The additive-only copy above preserves worktree-local files, but
     // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
     // syncs it to the project root, the worktree may retain a stale copy (e.g.
     // verdict:fail while the project root has verdict:pass from a retry). On
@@ -296,11 +341,9 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
     // Project root is authoritative for completion state after crash recovery;
     // without this, the worktree re-dispatches already-completed units (#1886).
     safeCopy(join(prGsd, "completed-units.json"), join(wtGsd, "completed-units.json"), { force: true });
-    // Delete worktree gsd.db ONLY if it is empty (0 bytes).
-    // An empty DB is stale/corrupt and should be rebuilt (#853).
-    // A non-empty DB was populated by gsd-migrate on respawn and must be
-    // preserved — deleting it truncates the file to 0 bytes when
-    // openDatabase re-creates it, causing "no such table" failures (#2815).
+    // Delete a legacy worktree-local gsd.db ONLY if it is empty (0 bytes).
+    // Runtime opens contract.projectDb; this cleanup only removes corrupt
+    // pre-upgrade local DB projections.
     try {
         const wtDb = join(wtGsd, "gsd.db");
         let deleteSidecars = false;
@@ -335,33 +378,57 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
     }
 }
 /**
- * Sync dispatch-critical .gsd/ state files from worktree to project root.
+ * Scope-typed variant of syncStateToProjectRoot.
+ *
+ * Takes an explicit (worktreeScope, rootScope) pair. Direction is encoded in
+ * argument order (worktree → root). Asserts both scopes belong to the same
+ * workspace identity to prevent silent mismatch bugs.
+ */
+export function syncStateToProjectRootByScope(worktreeScope, rootScope) {
+    if (worktreeScope.workspace.identityKey !== rootScope.workspace.identityKey) {
+        throw new Error(`syncStateToProjectRootByScope: scope identity mismatch — ` +
+            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}" ` +
+            `rootScope.identityKey="${rootScope.workspace.identityKey}"`);
+    }
+    if (worktreeScope.milestoneId !== rootScope.milestoneId) {
+        throw new Error(`syncStateToProjectRootByScope: milestoneId mismatch — ` +
+            `worktreeScope.milestoneId="${worktreeScope.milestoneId}" rootScope.milestoneId="${rootScope.milestoneId}"`);
+    }
+    const worktreePath_ = worktreeScope.workspace.worktreeRoot ?? worktreeScope.workspace.projectRoot;
+    const projectRoot = rootScope.workspace.projectRoot;
+    const milestoneId = worktreeScope.milestoneId;
+    syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId);
+}
+/**
+ * Sync worktree diagnostics from worktree to project root.
  * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
- * Copies: STATE.md + active milestone directory (roadmap, slice plans, task summaries).
+ * DB/project-root state remains authoritative; markdown projections are not
+ * copied from the worktree back to the project root.
  * Non-fatal — sync failure should never block dispatch.
+ * @deprecated Use syncStateToProjectRootByScope instead.
+ * TODO(C-future): remove once all callers migrated.
  */
 export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
     if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
         return;
     if (!milestoneId)
         return;
-    const wtGsd = join(worktreePath_, ".gsd");
-    const prGsd = join(projectRoot, ".gsd");
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+    const prGsd = contract.projectGsd;
     // When .gsd is a symlink to the same external directory in both locations,
     // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
     // Compare realpaths and skip when they resolve to the same physical path (#2184).
     if (isSamePath(wtGsd, prGsd))
         return;
-    // 1. STATE.md — the quick-glance status used by initial deriveState()
-    safeCopy(join(wtGsd, "STATE.md"), join(prGsd, "STATE.md"), { force: true });
-    // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
-    // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
-    safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
-    // 3. metrics.json — session cost/token tracking (#2313).
+    // metrics.json — session cost/token tracking (#2313).
     // Without this, metrics accumulated in the worktree are invisible from the
     // project root and never appear in the dashboard or skill-health reports.
     safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
-    // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
+    // completed-units.json — runtime completion diagnostics used to avoid
+    // re-dispatching work already completed in an isolated worktree.
+    safeCopy(join(wtGsd, "completed-units.json"), join(prGsd, "completed-units.json"), { force: true });
+    // Runtime records — unit dispatch diagnostics used by selfHealRuntimeRecords().
     // Without this, a crash during a unit leaves the runtime record only in the
     // worktree. If the next session resolves basePath before worktree re-entry,
     // selfHeal can't find or clear the stale record (#769).
@@ -374,7 +441,7 @@ export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId)
  * doesn't falsely trigger staleness (#804).
  */
 export function readResourceVersion() {
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
     const manifestPath = join(agentDir, "managed-resources.json");
     try {
         const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -432,9 +499,9 @@ export function escapeStaleWorktree(base) {
     // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
     // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
     // resolved through the symlink. Returning ~ would be catastrophic (#1676).
-    const candidateGsd = join(projectRoot, ".gsd").replaceAll("\\", "/");
-    const gsdHomePath = gsdHome.replaceAll("\\", "/");
-    if (candidateGsd === gsdHomePath || candidateGsd.startsWith(gsdHomePath + "/")) {
+    const candidateGsd = normalizeWorktreePathForCompare(join(projectRoot, ".gsd"));
+    const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
+    if (candidateGsd === gsdHomeNorm || candidateGsd.startsWith(gsdHomeNorm + "/")) {
         // Don't chdir to home — return base unchanged.
         // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
         // and will be called by the caller (startAuto → projectRoot()).
@@ -466,6 +533,29 @@ export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
         for (const file of readdirSync(runtimeUnitsDir)) {
             if (!file.endsWith(".json"))
                 continue;
+            if (LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES.has(file)) {
+                try {
+                    unlinkSync(join(runtimeUnitsDir, file));
+                    cleaned++;
+                }
+                catch (err) {
+                    /* non-fatal */
+                    logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                continue;
+            }
+            const staleDiscussMatch = file.match(/^discuss-milestone-(.+)\.json$/);
+            if (staleDiscussMatch && !MILESTONE_ID_RE.test(staleDiscussMatch[1])) {
+                try {
+                    unlinkSync(join(runtimeUnitsDir, file));
+                    cleaned++;
+                }
+                catch (err) {
+                    /* non-fatal */
+                    logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                continue;
+            }
             const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
             if (!midMatch)
                 continue;
@@ -488,6 +578,24 @@ export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
     return cleaned;
 }
 // ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
+/**
+ * Scope-typed variant of syncGsdStateToWorktree.
+ *
+ * Takes an explicit (rootScope, worktreeScope) pair. Note: milestoneId is not
+ * used by syncGsdStateToWorktree — this variant only requires workspace
+ * identity. Asserts both scopes belong to the same workspace identity to
+ * prevent silent mismatch bugs.
+ */
+export function syncGsdStateToWorktreeByScope(rootScope, worktreeScope) {
+    if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
+        throw new Error(`syncGsdStateToWorktreeByScope: scope identity mismatch — ` +
+            `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
+            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`);
+    }
+    const mainBasePath = rootScope.workspace.projectRoot;
+    const worktreePath_ = worktreeScope.workspace.worktreeRoot ?? worktreeScope.workspace.projectRoot;
+    return syncGsdStateToWorktree(mainBasePath, worktreePath_);
+}
 /**
  * Sync .gsd/ state from the main repo into the worktree.
  *
@@ -499,12 +607,16 @@ export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
  * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
  * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
  *
- * Only adds missing content — never overwrites existing files in the worktree
- * (the worktree's execution state is authoritative for in-progress work).
+ * Only adds missing content — never overwrites existing files in the worktree.
+ * Worktree files are compatibility projections; DB/project root remains
+ * authoritative for runtime state.
+ * @deprecated Use syncGsdStateToWorktreeByScope instead.
+ * TODO(C-future): remove once all callers migrated.
  */
 export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
-    const mainGsd = gsdRoot(mainBasePath);
-    const wtGsd = gsdRoot(worktreePath_);
+    const contract = resolveGsdPathContract(worktreePath_, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
     if (isSamePath(mainGsd, wtGsd))
@@ -648,28 +760,22 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     return { synced };
 }
 /**
- * Sync milestone artifacts from worktree back to the main external state directory.
- * Called before milestone merge to ensure completion artifacts (SUMMARY, VALIDATION,
- * updated ROADMAP) are visible from the project root (#1412).
+ * Sync compatibility artifacts from worktree back to the main external state
+ * directory. Canonical workflow state lives in the project DB; worktree .gsd
+ * content is legacy projection/diagnostic data only.
  *
  * Syncs:
- *   1. Root-level .gsd/ files (REQUIREMENTS, PROJECT, DECISIONS, KNOWLEDGE,
- *      OVERRIDES) — the worktree's versions overwrite main's because the
- *      worktree is the authoritative execution context.
- *   2. ALL milestone directories found in the worktree — not just the
- *      current milestoneId. The complete-milestone unit may create artifacts
- *      for the *next* milestone (CONTEXT, ROADMAP, new requirements) which
- *      must survive worktree teardown.
+ *   1. Legacy worktree DBs are reconciled into the canonical project DB.
+ *   2. Runtime diagnostic files may be copied for operator visibility.
  *
- * History: Originally only synced milestones/<milestoneId>/ and assumed
- * root-level files would be carried by the squash merge. In practice,
- * .gsd/ files are often untracked (gitignored or never committed), so the
- * squash merge carries nothing. This caused next-milestone artifacts and
- * updated REQUIREMENTS/PROJECT to be silently lost on teardown.
+ * Markdown milestone directories are projections and are not copied from
+ * worktrees into the project root. Current workflow state must arrive through
+ * the shared project DB or the pre-upgrade DB reconciliation path above.
  */
 export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
-    const mainGsd = gsdRoot(mainBasePath);
-    const wtGsd = gsdRoot(worktreePath);
+    const contract = resolveGsdPathContract(worktreePath, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath, ".gsd");
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
     if (isSamePath(mainGsd, wtGsd))
@@ -682,7 +788,7 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     // files. This handles in-flight worktrees that were created before the
     // upgrade to shared WAL mode.
     const wtLocalDb = join(wtGsd, "gsd.db");
-    const mainDb = join(mainGsd, "gsd.db");
+    const mainDb = contract.projectDb;
     if (existsSync(wtLocalDb) && existsSync(mainDb)) {
         try {
             reconcileWorktreeDb(mainDb, wtLocalDb);
@@ -693,13 +799,10 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
             logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // ── 1. Sync root-level .gsd/ files back ──────────────────────────────
-    // The worktree is authoritative — complete-milestone updates REQUIREMENTS,
-    // PROJECT, etc. These must overwrite main's copies so they survive teardown.
-    // Also includes QUEUE.md, completed-units.json, and metrics.json which are
-    // written during milestone closeout and lost on teardown without explicit sync
-    // (#1787, #2313).
-    for (const f of ROOT_STATE_FILES) {
+    // ── 1. Sync root-level diagnostic files back ─────────────────────────
+    // Markdown/JSON state projections remain project-root/DB authoritative.
+    // These diagnostic files are copied for observability only.
+    for (const f of ROOT_DIAGNOSTIC_FILES) {
         const src = join(wtGsd, f);
         const dst = join(mainGsd, f);
         if (existsSync(src)) {
@@ -713,92 +816,8 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
             }
         }
     }
-    // ── 2. Sync ALL milestone directories ────────────────────────────────
-    // The complete-milestone unit may create next-milestone artifacts (e.g.
-    // M007 setup while closing M006). We must sync every milestone directory
-    // in the worktree, not just the current one.
-    const wtMilestonesDir = join(wtGsd, "milestones");
-    if (!existsSync(wtMilestonesDir))
-        return { synced };
-    try {
-        const wtMilestones = readdirSync(wtMilestonesDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name);
-        for (const mid of wtMilestones) {
-            // Skip the current milestone being merged — its files are already in the
-            // milestone branch and would conflict with the squash merge (#3641).
-            if (mid === milestoneId)
-                continue;
-            syncMilestoneDir(wtGsd, mainGsd, mid, synced);
-        }
-    }
-    catch (err) {
-        /* non-fatal */
-        logWarning("worktree", `milestone sync-back failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
     return { synced };
 }
-/**
- * Sync a single milestone directory from worktree to main.
- * Copies milestone-level .md files, slice-level files, and task summaries.
- */
-/** Copy matching files from srcDir to dstDir (non-fatal per file). */
-function syncDirFiles(srcDir, dstDir, filter, synced, prefix) {
-    try {
-        for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-            if (!entry.isFile() || !filter(entry.name))
-                continue;
-            try {
-                cpSync(join(srcDir, entry.name), join(dstDir, entry.name), { force: true });
-                synced.push(`${prefix}${entry.name}`);
-            }
-            catch (err) {
-                /* non-fatal */
-                logWarning("worktree", `file copy failed (${prefix}${entry.name}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    catch (err) {
-        /* non-fatal — srcDir may not be readable */
-        logWarning("worktree", `directory read failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function syncMilestoneDir(wtGsd, mainGsd, mid, synced) {
-    const wtMilestoneDir = join(wtGsd, "milestones", mid);
-    const mainMilestoneDir = join(mainGsd, "milestones", mid);
-    if (!existsSync(wtMilestoneDir))
-        return;
-    mkdirSync(mainMilestoneDir, { recursive: true });
-    const isMd = (name) => name.endsWith(".md");
-    // Sync milestone-level files (SUMMARY, VALIDATION, ROADMAP, CONTEXT)
-    syncDirFiles(wtMilestoneDir, mainMilestoneDir, isMd, synced, `milestones/${mid}/`);
-    // Sync slice-level files (summaries, UATs) and task summaries (#1678)
-    const wtSlicesDir = join(wtMilestoneDir, "slices");
-    const mainSlicesDir = join(mainMilestoneDir, "slices");
-    if (!existsSync(wtSlicesDir))
-        return;
-    try {
-        for (const sliceEntry of readdirSync(wtSlicesDir, { withFileTypes: true })) {
-            if (!sliceEntry.isDirectory())
-                continue;
-            const sid = sliceEntry.name;
-            const wtSliceDir = join(wtSlicesDir, sid);
-            const mainSliceDir = join(mainSlicesDir, sid);
-            mkdirSync(mainSliceDir, { recursive: true });
-            syncDirFiles(wtSliceDir, mainSliceDir, isMd, synced, `milestones/${mid}/slices/${sid}/`);
-            const wtTasksDir = join(wtSliceDir, "tasks");
-            const mainTasksDir = join(mainSliceDir, "tasks");
-            if (existsSync(wtTasksDir)) {
-                mkdirSync(mainTasksDir, { recursive: true });
-                syncDirFiles(wtTasksDir, mainTasksDir, isMd, synced, `milestones/${mid}/slices/${sid}/tasks/`);
-            }
-        }
-    }
-    catch (err) {
-        /* non-fatal */
-        logWarning("worktree", `milestone slice sync failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 /**
  * Run the user-configured post-create hook script after worktree creation.
@@ -961,10 +980,35 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
  * directory at the project root and apply any [x] checkbox states that are
  * ahead of the worktree version (forward-only: never downgrade [x] → [ ]).
  *
- * This is safe because syncStateToProjectRoot() is the authoritative source
- * of post-task state at the project root — it writes the same [x] the LLM
- * produced, then the auto-commit follows. If the commit never happened, the
- * filesystem copy is still valid and correct.
+ * This is forward-only compatibility for legacy projection copies. The DB
+ * remains authoritative; this never downgrades checked boxes in a local
+ * worktree projection.
+ */
+/**
+ * Scope-typed variant of reconcilePlanCheckboxes.
+ *
+ * Takes an explicit (rootScope, worktreeScope) pair. milestoneId is taken
+ * from rootScope. Asserts both scopes belong to the same workspace identity
+ * to prevent silent mismatch bugs.
+ */
+export function reconcilePlanCheckboxesByScope(rootScope, worktreeScope) {
+    if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
+        throw new Error(`reconcilePlanCheckboxesByScope: scope identity mismatch — ` +
+            `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
+            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`);
+    }
+    if (rootScope.milestoneId !== worktreeScope.milestoneId) {
+        throw new Error(`reconcilePlanCheckboxesByScope: milestoneId mismatch — ` +
+            `rootScope.milestoneId="${rootScope.milestoneId}" worktreeScope.milestoneId="${worktreeScope.milestoneId}"`);
+    }
+    const projectRoot = rootScope.workspace.projectRoot;
+    const wtPath = worktreeScope.workspace.worktreeRoot ?? worktreeScope.workspace.projectRoot;
+    const milestoneId = rootScope.milestoneId;
+    reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId);
+}
+/**
+ * @deprecated Use reconcilePlanCheckboxesByScope instead.
+ * TODO(C-future): remove once all callers migrated.
  */
 function reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId) {
     const srcMilestone = join(projectRoot, ".gsd", "milestones", milestoneId);
@@ -1071,7 +1115,13 @@ export function createAutoWorktree(basePath, milestoneId) {
         // would fork worktrees from the wrong (stale) branch.
         const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
         const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-        const startPoint = integrationBranch ?? gitPrefs?.main_branch ?? undefined;
+        const validatedPrefBranch = gitPrefs?.main_branch &&
+            typeof gitPrefs.main_branch === "string" &&
+            gitPrefs.main_branch.length > 0 &&
+            nativeBranchExists(basePath, gitPrefs.main_branch)
+            ? gitPrefs.main_branch
+            : undefined;
+        const startPoint = integrationBranch ?? validatedPrefBranch ?? undefined;
         info = createWorktree(basePath, milestoneId, {
             branch,
             startPoint,
@@ -1113,11 +1163,11 @@ export function createAutoWorktree(basePath, milestoneId) {
     const previousCwd = process.cwd();
     try {
         process.chdir(info.path);
-        originalBase = basePath;
+        setActiveWorkspace(createWorkspace(basePath));
     }
     catch (err) {
         // If chdir fails, the worktree was created but we couldn't enter it.
-        // Don't store originalBase -- caller can retry or clean up.
+        // Don't set activeWorkspace -- caller can retry or clean up.
         throw new GSDError(GSD_IO_ERROR, `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`);
     }
     nudgeGitBranchCache(previousCwd);
@@ -1177,41 +1227,79 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false } = opts;
     const previousCwd = process.cwd();
+    // 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).
     try {
-        process.chdir(originalBasePath);
-        originalBase = null;
-    }
-    catch (err) {
-        throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    nudgeGitBranchCache(previousCwd);
-    removeWorktree(originalBasePath, milestoneId, {
-        branch,
-        deleteBranch: !preserveBranch,
-    });
-    // 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 (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 });
-        // Attempt a direct filesystem removal as a fallback — but ONLY if the
-        // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
-        if (isInsideWorktreesDir(originalBasePath, wtDir)) {
+        try {
+            process.chdir(originalBasePath);
+        }
+        catch (err) {
+            throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Mirror cleanup steps from mergeMilestoneToMain abort path:
+        // 1. Remove transient state files (STATE.md, auto.lock, {MID}-META.json).
+        //    Non-fatal — must not block teardown.
+        try {
+            clearProjectRootStateFiles(originalBasePath, milestoneId);
+        }
+        catch (err) {
+            logWarning("worktree", `clearProjectRootStateFiles failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // 2. Reconcile worktree-local gsd.db into project root DB if both exist.
+        //    Non-fatal — handles legacy worktrees that have a local copy.
+        if (isDbAvailable()) {
             try {
-                rmSync(wtDir, { recursive: true, force: true });
+                const contract = resolveGsdPathContract(previousCwd, originalBasePath);
+                const worktreeDbPath = join(contract.worktreeGsd ?? join(previousCwd, ".gsd"), "gsd.db");
+                const mainDbPath = contract.projectDb;
+                if (existsSync(worktreeDbPath) && !isSamePath(worktreeDbPath, mainDbPath)) {
+                    reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+                }
             }
             catch (err) {
-                // Non-fatal — the warning above tells the user how to clean up
-                logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
+                /* non-fatal */
+                logError("worktree", `DB reconciliation failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        else {
-            console.error(`[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`);
+        nudgeGitBranchCache(previousCwd);
+        // 3. Remove the worktree. Errors propagate naturally — the outer finally
+        //    ensures activeWorkspace is cleared regardless.
+        removeWorktree(originalBasePath, milestoneId, {
+            branch,
+            deleteBranch: !preserveBranch,
+        });
+        // 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 (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 });
+            // Attempt a direct filesystem removal as a fallback — but ONLY if the
+            // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
+            if (isInsideWorktreesDir(originalBasePath, wtDir)) {
+                try {
+                    rmSync(wtDir, { recursive: true, force: true });
+                }
+                catch (err) {
+                    // Non-fatal — the warning above tells the user how to clean up
+                    logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                console.error(`[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`);
+            }
         }
     }
+    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);
+    }
 }
 /**
  * Detect if the process is currently inside an auto-worktree.
@@ -1219,17 +1307,18 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    const cwd = process.cwd();
-    if (!isGsdWorktreePath(cwd))
+    const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+    if (!isGsdWorktreePath(targetPath))
         return false;
-    const projectRoot = resolveWorktreeProjectRoot(basePath, originalBase);
-    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    const storedBase = getAutoWorktreeOriginalBase();
+    const projectRoot = resolveWorktreeProjectRoot(basePath, storedBase);
+    const targetProjectRoot = resolveWorktreeProjectRoot(targetPath, storedBase);
     if (normalizeWorktreePathForCompare(projectRoot) !==
-        normalizeWorktreePathForCompare(cwdProjectRoot)) {
+        normalizeWorktreePathForCompare(targetProjectRoot)) {
         return false;
     }
     try {
-        const branch = nativeGetCurrentBranch(cwd);
+        const branch = nativeGetCurrentBranch(targetPath);
         return branch.startsWith("milestone/");
     }
     catch {
@@ -1296,7 +1385,7 @@ export function enterAutoWorktree(basePath, milestoneId) {
     const previousCwd = process.cwd();
     try {
         process.chdir(p);
-        originalBase = basePath;
+        setActiveWorkspace(createWorkspace(basePath));
     }
     catch (err) {
         throw new GSDError(GSD_IO_ERROR, `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`);
@@ -1309,14 +1398,16 @@ export function enterAutoWorktree(basePath, milestoneId) {
  * Returns null if not currently in an auto-worktree.
  */
 export function getAutoWorktreeOriginalBase() {
-    return originalBase;
+    return getActiveWorkspace()?.projectRoot ?? null;
 }
 export function _resetAutoWorktreeOriginalBaseForTests() {
-    originalBase = null;
+    setActiveWorkspace(null);
 }
 export function getActiveAutoWorktreeContext() {
-    if (!originalBase)
+    const ws = getActiveWorkspace();
+    if (!ws)
         return null;
+    const originalBase = ws.projectRoot;
     const cwd = process.cwd();
     if (!isGsdWorktreePath(cwd))
         return null;
@@ -1353,7 +1444,7 @@ function autoCommitDirtyState(cwd) {
     }
     catch (e) {
         debugLog("autoCommitDirtyState", { error: String(e) });
-        return false;
+        throw new GSDError(GSD_GIT_ERROR, `Failed to auto-commit dirty worktree state before milestone merge: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
 /**
@@ -1386,11 +1477,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //    integration branch captures dirty files from OTHER milestones under a
     //    misleading commit message, contaminating the main branch (#2929).
     //
-    //    When originalBase is null (branch mode, no worktree), autoCommitDirtyState
+    //    When activeWorkspace is null (branch mode, no worktree), autoCommitDirtyState
     //    runs unconditionally — the caller is responsible for cwd placement.
     {
         let shouldAutoCommit = true;
-        if (originalBase !== null) {
+        if (getActiveWorkspace() !== null) {
             try {
                 const currentBranch = nativeGetCurrentBranch(worktreeCwd);
                 shouldAutoCommit = currentBranch === milestoneBranch;
@@ -1410,9 +1501,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // database (#2823).
     if (isDbAvailable()) {
         try {
-            const worktreeDbPath = join(worktreeCwd, ".gsd", "gsd.db");
-            const mainDbPath = join(originalBasePath_, ".gsd", "gsd.db");
-            if (!isSamePath(worktreeDbPath, mainDbPath)) {
+            const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
+            const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+            const mainDbPath = contract.projectDb;
+            if (existsSync(worktreeDbPath) && !isSamePath(worktreeDbPath, mainDbPath)) {
                 reconcileWorktreeDb(mainDbPath, worktreeDbPath);
             }
         }
@@ -1966,7 +2058,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     }
     // 10. Auto-push if enabled
     let pushed = false;
-    if (prefs.auto_push === true && !nothingToCommit) {
+    if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
         const remote = prefs.remote ?? "origin";
         try {
             execFileSync("git", ["push", remote, mainBranch], {
@@ -2016,9 +2108,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //     throws only when the milestone has unanchored code changes, passes
     //     through when the code is genuinely already on the integration branch.
     // 11a. Pre-teardown safety net (#1853): if the worktree still has uncommitted
-    // changes (e.g. nativeHasChanges cache returned stale false, or auto-commit
-    // silently failed), force one final commit so code is not destroyed by
-    // `git worktree remove --force`.
+    // changes (e.g. nativeHasChanges cache returned stale false), abort teardown.
+    // Committing here would be too late: the squash merge to the integration
+    // branch already happened, so a new milestone-branch commit would not be
+    // included and branch deletion could drop the only ref to that work.
     //
     // Guard: only run when worktreeCwd is on the milestone branch (#2929).
     // In parallel mode or branch-mode merges, worktreeCwd may be the project
@@ -2037,18 +2130,16 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             try {
                 const dirtyCheck = nativeWorkingTreeStatus(worktreeCwd);
                 if (dirtyCheck) {
-                    debugLog("mergeMilestoneToMain", {
-                        phase: "pre-teardown-dirty",
-                        worktreeCwd,
-                        status: dirtyCheck.slice(0, 200),
-                    });
-                    nativeAddAllWithExclusions(worktreeCwd, RUNTIME_EXCLUSION_PATHS);
-                    nativeCommit(worktreeCwd, "chore: pre-teardown auto-commit of uncommitted worktree changes");
+                    process.chdir(previousCwd);
+                    throw new GSDError(GSD_GIT_ERROR, `Milestone worktree still has uncommitted changes after squash merge. ` +
+                        `Aborting teardown to preserve ${milestoneBranch}. Status:\n${dirtyCheck}`);
                 }
             }
             catch (e) {
+                if (e instanceof GSDError)
+                    throw e;
                 debugLog("mergeMilestoneToMain", {
-                    phase: "pre-teardown-commit-error",
+                    phase: "pre-teardown-dirty-check-error",
                     error: String(e),
                 });
             }
@@ -2074,7 +2165,22 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
     }
     // 14. Clear module state
-    originalBase = null;
+    setActiveWorkspace(null);
     nudgeGitBranchCache(previousCwd);
+    // 15. Anchor cwd at the project root on success-return. Step 12 removed
+    // the worktree dir; if cwd was inside it, every subsequent process.cwd()
+    // would throw ENOENT and trip auto/run-unit.ts:50's session-failed cancel
+    // path (the de73fb43d regression that closes headless gsd auto). Step 3
+    // already chdir'd here, but defending the success-return contract makes
+    // future maintainers safe against intervening chdir's between step 3 and
+    // here.
+    try {
+        // process.cwd() can throw ENOENT when cwd was removed, so attempt
+        // recovery directly.
+        process.chdir(originalBasePath_);
+    }
+    catch (err) {
+        logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     return { commitMessage, pushed, prCreated, codeFilesChanged };
 }