@opengsd/gsd-pi 1.4.0-dev.c18009cd → 1.5.0-dev.553dc518

package/README.md

@@ -28,16 +28,16 @@ See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Rele
 ## Latest Release Highlights
 
 <!-- release-highlights:start -->
-Latest release: **v1.4.0**
-
-- **models:** Add Claude Sonnet 5.
-- **Added:** Add Hermes plugin installer.
-- **compat:** Report .planning/ drift in /gsd sync and doctor.
-- **compat:** Project to .planning/ inside renderAllFromDb.
-- **compat:** Add external-planning-edit drift handler.
-- **compat:** Add DB → .planning/ projection writer.
-- **compat:** Extract .planning/ layout detector.
-- **compat:** Extend marker schema 1→2 with planning field.
+Latest release: **v1.5.0**
+
+- **hermes:** Add /gsd new-milestone command for chat-driven milestone creation (#1162).
+- **gsd:** Make CODEBASE.md workspace-aware in parent mode.
+- **gsd:** Doctor probe + validation for parent-workspace repos.
+- **gsd:** Surface per-repo git health in /gsd status + document limits.
+- **gsd:** Wire repository assignment into slice/task planning.
+- **gsd:** Add parent-workspace discovery UX + document nested-only layout.
+- **provider:** Add Cursor Agent provider.
+- **gsd:** Make workspace.mode parent behavioral (mode contract).
 
 <!-- release-highlights:end -->
 

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-f30abebf080db301
+be3c5dc39486dc24

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

@@ -1,12 +1,17 @@
 // Project/App: gsd-pi
 // File Purpose: Auto-loop closeout, milestone report, and merge helpers.
 import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join, basename } from "node:path";
+import { readFileSync } from "node:fs";
 import { MergeConflictError } from "../git-service.js";
 import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
 import { getIsolationMode } from "../preferences.js";
 import { isDbAvailable, getMilestone } from "../gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { isClosedStatus } from "../status-guards.js";
+import { PLANNING_ARTIFACT_SUFFIXES } from "../paths.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
 import { _resolveReportBasePath } from "./phase-helpers.js";
@@ -51,7 +56,15 @@ export async function restorePreflightStashOrStop(ic, preflight, milestoneId) {
  */
 export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, options = {}) {
     const { ctx, pi, s, deps } = ic;
-    const projectRoot = s.originalBasePath || s.basePath;
+    // Resolve the project root once, before the merge can flip session path
+    // pointers (worktree teardown mutates s.basePath / s.scope). The guarded
+    // merge's preflight/postflight stash restore, the pre-merge ignored-markdown
+    // snapshot, the dirty-projection check, and the rebuild must all target this
+    // same tree; otherwise `.gsd` markdown restored on one tree can be silently
+    // overwritten by a rebuild on another. canonicalProjectRoot is the
+    // authoritative `.gsd`/DB writer path (see AutoSession.canonicalProjectRoot).
+    const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+    const ignoredProjectionSnapshot = snapshotIgnoredGsdMarkdownProjections(projectRoot);
     const mergeResult = deps.lifecycle.exitMilestone(milestoneId, {
         merge: true,
         guardedMerge: {
@@ -61,11 +74,11 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, option
         },
     }, ctx.ui);
     if (mergeResult.ok) {
-        await markMilestoneMergedAndRebuild(s);
+        await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
         return null;
     }
     if (mergeResult.reason === "postflight-stash-restore-failed") {
-        await markMilestoneMergedAndRebuild(s);
+        await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
     }
     if (mergeResult.reason === "preflight-dirty-overlap" || mergeResult.reason === "preflight-unmerged-conflicts") {
         const reason = mergeResult.reason === "preflight-unmerged-conflicts"
@@ -122,10 +135,13 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, option
     }
     return null;
 }
-async function markMilestoneMergedAndRebuild(s) {
+async function markMilestoneMergedAndRebuild(s, rebuildBasePath, ignoredProjectionSnapshot) {
     s.milestoneMergedInPhases = true;
+    if (hasDirtyGsdMarkdownProjections(rebuildBasePath, ignoredProjectionSnapshot)) {
+        logWarning("engine", "skipping markdown projection rebuild after milestone merge because restored .gsd edits are dirty");
+        return;
+    }
     try {
-        const rebuildBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
         const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
         await rebuildMarkdownProjectionsFromDb(rebuildBasePath);
     }
@@ -133,6 +149,82 @@ async function markMilestoneMergedAndRebuild(s) {
         logWarning("engine", `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+function hasDirtyGsdMarkdownProjections(basePath, ignoredProjectionSnapshot) {
+    try {
+        const output = execFileSync("git", ["status", "--porcelain", "-z", "--untracked-files=all", "--", ".gsd"], { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const entries = output.split("\0").filter(Boolean);
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.length <= 3)
+                continue;
+            const status = entry.slice(0, 2);
+            const path = entry.slice(3);
+            if (isGeneratedGsdMarkdownProjection(path))
+                return true;
+            if ((status === "R " || status === "C ") && i + 1 < entries.length) {
+                const dest = entries[++i];
+                if (isGeneratedGsdMarkdownProjection(dest))
+                    return true;
+            }
+        }
+    }
+    catch (err) {
+        void err;
+        // Fall through to ignored-file snapshot comparison below.
+    }
+    return ignoredGsdMarkdownProjectionSnapshotChanged(basePath, ignoredProjectionSnapshot);
+}
+function isGeneratedGsdMarkdownProjection(path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (normalized === ".gsd/DECISIONS.md")
+        return true;
+    if (!normalized.startsWith(".gsd/milestones/") && !normalized.startsWith(".gsd/phases/")) {
+        return false;
+    }
+    return isGeneratedPlanningArtifactFileName(basename(normalized));
+}
+function isGeneratedPlanningArtifactFileName(fileName) {
+    if (!fileName.endsWith(".md"))
+        return false;
+    const stem = fileName.slice(0, -".md".length).toUpperCase();
+    for (const suffix of PLANNING_ARTIFACT_SUFFIXES) {
+        if (!stem.endsWith(`-${suffix}`))
+            continue;
+        const idPrefix = stem.slice(0, -suffix.length - 1);
+        return /^(?:[MST]\d+|\d{2,})(?:-[A-Z0-9]+)*$/.test(idPrefix);
+    }
+    return false;
+}
+function snapshotIgnoredGsdMarkdownProjections(basePath) {
+    try {
+        const output = execFileSync("git", ["ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", ".gsd"], { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const snapshot = new Map();
+        for (const path of output.split("\0")) {
+            if (!isGeneratedGsdMarkdownProjection(path))
+                continue;
+            snapshot.set(path, hashFile(join(basePath, path)));
+        }
+        return snapshot;
+    }
+    catch {
+        return null;
+    }
+}
+function hashFile(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function ignoredGsdMarkdownProjectionSnapshotChanged(basePath, before) {
+    if (!before)
+        return true;
+    const after = snapshotIgnoredGsdMarkdownProjections(basePath);
+    if (!after || after.size !== before.size)
+        return true;
+    for (const [path, hash] of before) {
+        if (after.get(path) !== hash)
+            return true;
+    }
+    return false;
+}
 export async function _runMilestoneMergeOnceWithStashRestore(ic, milestoneId, options = {}) {
     if (ic.s.milestoneMergedInPhases) {
         debugLog("autoLoop", {

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

@@ -21,7 +21,8 @@ import { createWorktreeSafetyModule } from "../worktree-safety.js";
 import { repairAutoWorktreeSafetyFailure } from "../auto-worktree-repair.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { preDispatchHealthGate, recordHealthSnapshot, } from "../doctor-proactive.js";
-import { checkResourcesStale, autoWorktreeBranch, mergeMilestoneToMain } from "../auto-worktree.js";
+import { autoWorktreeBranch } from "../auto-worktree-branch-lifecycle.js";
+import { checkResourcesStale } from "../auto-worktree-resource-version.js";
 import { getSessionLockStatus } from "../session-lock.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { emitJournalEvent as _emitJournalEvent } from "../journal.js";
@@ -31,7 +32,7 @@ import { getPriorSliceCompletionBlocker } from "../dispatch-guard.js";
 import { GitServiceImpl } from "../git-service.js";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import { WorktreeLifecycle } from "../worktree-lifecycle.js";
-import { createMilestoneMergeTransaction } from "../milestone-merge-transaction.js";
+import { createDefaultMilestoneMergeTransaction } from "../milestone-merge-transaction.js";
 import { createWorkspace, scopeMilestone } from "../workspace.js";
 import { supportsStructuredQuestions } from "../workflow-mcp.js";
 import { getRegisteredToolSnapshot, getToolBaselineSnapshot } from "../auto-model-selection.js";
@@ -560,7 +561,7 @@ export class AutoOrchestrator {
                 return new GitServiceImpl(basePath, gitConfig);
             },
             worktreeProjection: new WorktreeStateProjection(),
-            mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
+            mergeMilestone: createDefaultMilestoneMergeTransaction(),
         });
     }
     rebuildScope(rawPath, milestoneId) {

package/dist/resources/extensions/gsd/auto/pre-dispatch.js

@@ -345,7 +345,8 @@ export async function runPreDispatch(ic, loopState) {
             if (stop)
                 return stop;
         }
-        // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+        // PR creation (auto_pr) is handled by the publication handoff in
+        // the milestone merge transaction (#2302).
         deps.invalidateAllCaches();
         state = await deps.deriveState(s.canonicalProjectRoot);
         mid = state.activeMilestone?.id;
@@ -430,7 +431,8 @@ export async function runPreDispatch(ic, loopState) {
                 const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
                 if (stop)
                     return stop;
-                // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+                // PR creation (auto_pr) is handled by the publication handoff in
+                // the milestone merge transaction (#2302).
             }
             const unmappedActive = countUnmappedActiveRequirements();
             const completionStopReason = formatCompletePhaseNextAction(unmappedActive);
@@ -506,7 +508,8 @@ export async function runPreDispatch(ic, loopState) {
             const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
             if (stop)
                 return stop;
-            // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+            // PR creation (auto_pr) is handled by the publication handoff in
+            // the milestone merge transaction (#2302).
         }
         deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone", basename(s.originalBasePath || s.basePath));
         deps.logCmuxEvent(prefs, `Milestone ${mid} complete.`, "success");

package/dist/resources/extensions/gsd/auto/unit-phase.js

@@ -17,7 +17,7 @@ import { isDbAvailable, getTask } from "../gsd-db.js";
 import { parseUnitId } from "../unit-id.js";
 import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
 import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
-import { getUnitWorkflowDispatchReadinessError } from "../tool-contract.js";
+import { getUnitWorkflowDispatchReadinessErrorForModel } from "../tool-contract.js";
 import { prepareWorkflowMcpForProject } from "../workflow-mcp-auto-prep.js";
 import { applyThinkingLevelForModel, floorThinkingLevelForUnit, } from "../auto-model-selection.js";
 import { isSuspiciousGhostCompletion } from "../auto-unit-closeout.js";
@@ -246,17 +246,13 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     s.currentDispatchedModelId = s.currentUnitModel
         ? `${s.currentUnitModel.provider ?? ""}/${s.currentUnitModel.id ?? ""}`
         : null;
-    const compatibilityError = getUnitWorkflowDispatchReadinessError({
-        provider: s.currentUnitModel?.provider ?? ctx.model?.provider,
+    const compatibilityError = getUnitWorkflowDispatchReadinessErrorForModel({
+        model: s.currentUnitModel,
+        fallbackModel: ctx.model,
+        getProviderAuthMode: (provider) => ctx.modelRegistry.getProviderAuthMode(provider),
         projectRoot: s.basePath,
         surface: "auto-mode",
         unitType,
-        authMode: s.currentUnitModel?.provider
-            ? ctx.modelRegistry.getProviderAuthMode(s.currentUnitModel.provider)
-            : ctx.model?.provider
-                ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-                : undefined,
-        baseUrl: s.currentUnitModel?.baseUrl ?? ctx.model?.baseUrl,
         activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
     });
     const workflowMcpPrepModel = s.currentUnitModel;

package/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -10,7 +10,7 @@ import { buildResearchSlicePrompt, buildResearchMilestonePrompt, buildPlanSliceP
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { pauseAuto } from "./auto.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
-import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
+import { getUnitWorkflowDispatchReadinessErrorForModel } from "./tool-contract.js";
 export function parseDirectDispatchPhase(raw) {
     const tokens = raw.trim().split(/\s+/).filter(Boolean);
     if (tokens.length === 0)
@@ -213,13 +213,12 @@ export async function dispatchDirectPhase(ctx, pi, phase, base, opts = {}) {
             ctx.ui.notify(`Unknown phase "${phase}". Valid phases: research, plan, execute, complete, validate, reassess, uat, replan.`, "warning");
             return;
     }
-    const compatibilityError = getUnitWorkflowDispatchReadinessError({
-        provider: ctx.model?.provider,
+    const compatibilityError = getUnitWorkflowDispatchReadinessErrorForModel({
+        model: ctx.model,
+        getProviderAuthMode: (provider) => ctx.modelRegistry.getProviderAuthMode(provider),
         projectRoot,
         surface: "direct phase dispatch",
         unitType,
-        authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
-        baseUrl: ctx.model?.baseUrl,
         activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
     });
     if (compatibilityError) {

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

@@ -27,9 +27,10 @@ import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, nativeHasChanges, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
-import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
+import { cleanStaleRuntimeUnits } from "./auto-worktree-runtime-cleanup.js";
+import { readResourceVersion } from "./auto-worktree-resource-version.js";
 import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { emitWorktreeOrphaned } from "./worktree-telemetry.js";
 import { queryJournal } from "./journal.js";

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

@@ -0,0 +1,189 @@
+// gsd-pi — Auto-worktree branch lifecycle module.
+//
+// Owns milestone branch naming, branch-mode entry, and safe fast-forward of
+// reused milestone branches. Worktree creation/merge code imports this module
+// instead of keeping branch policy inside the legacy auto-worktree barrel.
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { debugLog } from "./debug-logger.js";
+import { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
+import { nativeBranchExists, nativeBranchForceReset, nativeDetectMainBranch, nativeIsAncestor, nativeUpdateRef, nativeWorktreeList, } from "./native-git-bridge.js";
+/** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
+export function autoWorktreeBranch(milestoneId) {
+    return `milestone/${milestoneId}`;
+}
+export function _resolveAutoWorktreeStartPoint(integrationBranch, gitMainBranch, branchExists) {
+    if (integrationBranch)
+        return integrationBranch;
+    return gitMainBranch &&
+        typeof gitMainBranch === "string" &&
+        gitMainBranch.length > 0 &&
+        branchExists(gitMainBranch)
+        ? gitMainBranch
+        : undefined;
+}
+/**
+ * Enter branch isolation mode for a milestone.
+ *
+ * Creates `milestone/<MID>` from the integration branch (if it doesn't
+ * exist yet) and checks out to it. No worktree directory is created — the
+ * project root is the working copy; only HEAD changes.
+ *
+ * Uses the same 3-tier integration-branch fallback as createAutoWorktree:
+ *   1. META.json recorded integration branch
+ *   2. git.main_branch preference
+ *   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+ */
+export function enterBranchModeForMilestone(basePath, milestoneId) {
+    const branch = autoWorktreeBranch(milestoneId);
+    const branchExists = nativeBranchExists(basePath, branch);
+    if (!branchExists) {
+        // Create the milestone branch from the integration branch start-point.
+        const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
+        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        const startPoint = _resolveAutoWorktreeStartPoint(integrationBranch, gitPrefs?.main_branch, (branchName) => nativeBranchExists(basePath, branchName)) ??
+            nativeDetectMainBranch(basePath);
+        // TOCTOU ancestry guard (Issue #4980 HIGH-3).
+        //
+        // The outer `branchExists` check is racy: a concurrent process
+        // (parallel-orchestrator worker, side-by-side `gsd` instance, or manual
+        // `git branch` invocation) may have created the branch with real commits
+        // between that check and this point. `nativeBranchForceReset` does
+        // `git branch -f`, which silently overwrites the branch ref — orphaning
+        // any commits not reachable from `startPoint`. Re-check immediately
+        // before the destructive call and refuse if the branch suddenly exists
+        // with non-ancestor commits.
+        const concurrentlyCreated = nativeBranchExists(basePath, branch);
+        if (concurrentlyCreated &&
+            !nativeIsAncestor(basePath, branch, startPoint)) {
+            throw new GSDError(GSD_GIT_ERROR, `Branch "${branch}" was created concurrently with commits not reachable from "${startPoint}". ` +
+                `Refusing to force-reset — would orphan prior work. ` +
+                `Resume the existing milestone or run \`git branch -D ${branch}\` to discard.`);
+        }
+        // nativeBranchForceReset creates (or resets) branch at startPoint,
+        // then checkout switches HEAD to it.
+        nativeBranchForceReset(basePath, branch, startPoint);
+        debugLog("auto-worktree", {
+            action: "enterBranchMode",
+            milestoneId,
+            branch,
+            startPoint,
+            created: true,
+        });
+    }
+    else {
+        debugLog("auto-worktree", {
+            action: "enterBranchMode",
+            milestoneId,
+            branch,
+            reused: true,
+        });
+    }
+    checkoutBranchWithStashGuard(basePath, branch, `enter-branch-mode:${milestoneId}`);
+}
+/**
+ * True when `branch` is checked out in any worktree listed by
+ * `git worktree list --porcelain`. Used to gate ref updates that would
+ * otherwise leave a concurrent worktree's HEAD inconsistent with its
+ * index/working tree (Codex peer-review of #5538-followup).
+ *
+ * Best-effort: a `nativeWorktreeList` failure returns true so we err on
+ * the side of NOT moving the ref. Better to skip a fast-forward than to
+ * silently corrupt another worktree.
+ */
+export function _isBranchCheckedOutElsewhere(basePath, branch) {
+    try {
+        const entries = nativeWorktreeList(basePath);
+        return entries.some((entry) => entry.branch === branch);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Resolve the integration branch using the same 3-tier fallback as the
+ * fresh-create path: META.json → git.main_branch preference → detected
+ * main branch. Returns null when no usable target exists.
+ */
+function resolveIntegrationBranchForReuse(basePath, milestoneId) {
+    const fromMeta = readIntegrationBranch(basePath, milestoneId);
+    if (fromMeta)
+        return fromMeta;
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    const fromPref = gitPrefs?.main_branch &&
+        typeof gitPrefs.main_branch === "string" &&
+        gitPrefs.main_branch.length > 0 &&
+        nativeBranchExists(basePath, gitPrefs.main_branch)
+        ? gitPrefs.main_branch
+        : null;
+    if (fromPref)
+        return fromPref;
+    try {
+        return nativeDetectMainBranch(basePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When reusing an existing milestone branch, fast-forward it onto the
+ * integration branch when that's safe (branch is a strict ancestor of
+ * integration — no commits would be lost). Skips when the branch has its
+ * own commits ahead of integration, when the integration branch can't be
+ * resolved, or when any git operation fails — the merge gate at milestone
+ * completion will surface real divergence as a conflict.
+ *
+ * The previous behavior re-attached the worktree to whatever stale tip
+ * the branch held, which caused new milestone work to fork from a base
+ * missing prior milestones' merges (#5538-followup).
+ */
+export function fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch) {
+    try {
+        const integrationBranch = resolveIntegrationBranchForReuse(basePath, milestoneId);
+        if (!integrationBranch || integrationBranch === branch)
+            return;
+        if (!nativeBranchExists(basePath, integrationBranch))
+            return;
+        // Pure fast-forward only: branch must be a strict ancestor of integration.
+        // If the branch has its own commits ahead, leave it alone.
+        if (!nativeIsAncestor(basePath, branch, integrationBranch)) {
+            debugLog("createAutoWorktree", {
+                phase: "skip-ff-branch-not-ancestor",
+                milestoneId,
+                branch,
+                integration: integrationBranch,
+            });
+            return;
+        }
+        // Codex peer-review: `nativeUpdateRef` succeeds even when the branch is
+        // currently checked out in another worktree, leaving that worktree's HEAD
+        // inconsistent with its index/work tree. Skip the fast-forward if any
+        // listed worktree has this branch checked out — the merge gate at
+        // milestone-completion will surface stale-base divergence as a conflict
+        // instead of silently corrupting the other worktree's state.
+        if (_isBranchCheckedOutElsewhere(basePath, branch)) {
+            debugLog("createAutoWorktree", {
+                phase: "skip-ff-branch-checked-out-elsewhere",
+                milestoneId,
+                branch,
+            });
+            return;
+        }
+        nativeUpdateRef(basePath, `refs/heads/${branch}`, integrationBranch);
+        debugLog("createAutoWorktree", {
+            phase: "fast-forward-reused-branch",
+            milestoneId,
+            branch,
+            integration: integrationBranch,
+        });
+    }
+    catch (err) {
+        debugLog("createAutoWorktree", {
+            phase: "fast-forward-reused-branch-failed",
+            milestoneId,
+            branch,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

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

@@ -0,0 +1,133 @@
+// gsd-pi — Auto-worktree cleanup helpers.
+//
+// Owns shared cleanup primitives used by teardown and merge cleanup paths:
+// same-file DB reconciliation checks, transient project-root state removal,
+// git pathspec conversion for externally-rooted .gsd paths, and expected
+// unlink error classification.
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
+function isSamePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return false;
+        logWarning("worktree", `isSamePath failed: ${e.message}`);
+        return false;
+    }
+}
+export function _isSamePath(a, b) {
+    return isSamePath(a, b);
+}
+export function _shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath, pathExists = existsSync, samePath = isSamePath) {
+    return pathExists(worktreeDbPath) && !samePath(worktreeDbPath, mainDbPath);
+}
+export function _isExpectedWorktreeUnlinkError(code) {
+    return code === "ENOENT" || code === "EISDIR";
+}
+function gitPathspecForWorktreePath(basePath, targetPath) {
+    let base = basePath;
+    let target = targetPath;
+    try {
+        base = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        }).trim() || basePath;
+    }
+    catch {
+        /* keep original */
+        void base;
+    }
+    try {
+        base = realpathSync.native(base);
+    }
+    catch {
+        /* keep original */
+        void base;
+    }
+    try {
+        target = realpathSync.native(targetPath);
+    }
+    catch {
+        /* keep original */
+        void target;
+    }
+    const rel = relative(base, target);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return rel.replaceAll("\\", "/");
+}
+export function _gitPathspecForWorktreePath(basePath, targetPath) {
+    return gitPathspecForWorktreePath(basePath, targetPath);
+}
+export function clearProjectRootStateFiles(basePath, milestoneId) {
+    const gsdDir = gsdRoot(basePath);
+    // Phase C pt 2: auto.lock removed from this list — the file is gone
+    // (migrated to the workers + unit_dispatches + runtime_kv tables). The
+    // remaining transient files (STATE.md, {MID}-META.json) are still
+    // worth removing on teardown.
+    const transientFiles = [
+        join(gsdDir, "STATE.md"),
+        join(gsdDir, "milestones", milestoneId, `${milestoneId}-META.json`),
+    ];
+    for (const file of transientFiles) {
+        try {
+            unlinkSync(file);
+        }
+        catch (err) {
+            // ENOENT is expected — file may not exist (#3597)
+            if (err.code !== "ENOENT") {
+                logWarning("worktree", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    // 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 = [
+        join(gsdDir, "milestones", milestoneId),
+        join(gsdDir, "runtime", "units"),
+    ];
+    for (const dir of syncedDirs) {
+        try {
+            if (!existsSync(dir))
+                continue;
+            const pathspec = gitPathspecForWorktreePath(basePath, dir);
+            if (!pathspec)
+                continue;
+            // Only remove files that are untracked by git — tracked files are
+            // managed by the branch checkout and should not be deleted.
+            const untrackedOutput = execFileSync("git", ["ls-files", "--others", "--exclude-standard", pathspec], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim();
+            if (!untrackedOutput)
+                continue;
+            for (const f of untrackedOutput.split("\n").filter(Boolean)) {
+                try {
+                    unlinkSync(join(basePath, f));
+                }
+                catch (err) {
+                    // ENOENT/EISDIR are expected for already-removed or
+                    // directory entries (#3597).
+                    const code = err.code;
+                    if (!_isExpectedWorktreeUnlinkError(code)) {
+                        logWarning("worktree", `untracked file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            /* non-fatal — git command may fail if not in repo */
+            logWarning("worktree", `untracked file cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}