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

package/pkg/dist/core/export-html/template.js

@@ -894,15 +894,64 @@
         const isError = result?.isError || false;
         const statusClass = result ? (isError ? 'error' : 'success') : 'pending';
 
+        // This template runs as a standalone browser script in exported HTML,
+        // so it cannot import normalizeToolResultContent from @gsd/pi-ai.
+        // Keep these fallback semantics aligned with that helper.
+        const stringifyResultContent = (content) => {
+          try {
+            const value = JSON.stringify(content);
+            if (typeof value === 'string') return value;
+          } catch {
+            // Fall through to String(content). JSON.stringify can throw for cycles.
+          }
+
+          try {
+            return String(content);
+          } catch {
+            return '[unstringifiable tool result content]';
+          }
+        };
+
+        const serializableCacheControl = (block) => {
+          if (!block || typeof block !== 'object' || !('cache_control' in block)) return {};
+          try {
+            JSON.stringify(block.cache_control);
+            return { cache_control: block.cache_control };
+          } catch {
+            return {};
+          }
+        };
+
+        const normalizeResultContentBlock = (block) => {
+          if (typeof block === 'string') return { type: 'text', text: block };
+          if (block && typeof block === 'object') {
+            const cacheControl = serializableCacheControl(block);
+            if (block.type === 'text' && typeof block.text === 'string') return { type: 'text', text: block.text, ...cacheControl };
+            if (block.type === 'image' && typeof block.data === 'string' && typeof block.mimeType === 'string') {
+              return { type: 'image', data: block.data, mimeType: block.mimeType, ...cacheControl };
+            }
+          }
+          return { type: 'text', text: stringifyResultContent(block) };
+        };
+
+        const getResultContent = () => {
+          if (!result) return [];
+          if (Array.isArray(result.content)) {
+            const blocks = result.content.map(normalizeResultContentBlock);
+            return blocks.length > 0 ? blocks : [{ type: 'text', text: '' }];
+          }
+          if (typeof result.content === 'string') return [{ type: 'text', text: result.content }];
+          if (result.content == null) return [{ type: 'text', text: '' }];
+          return [{ type: 'text', text: stringifyResultContent(result.content) }];
+        };
+
         const getResultText = () => {
-          if (!result) return '';
-          const textBlocks = result.content.filter(c => c.type === 'text');
+          const textBlocks = getResultContent().filter(c => c.type === 'text');
           return textBlocks.map(c => c.text).join('\n');
         };
 
         const getResultImages = () => {
-          if (!result) return [];
-          return result.content.filter(c => c.type === 'image');
+          return getResultContent().filter(c => c.type === 'image');
         };
 
         const renderResultImages = () => {

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "1.4.0-dev.c18009cd",
+  "version": "1.5.0-dev.553dc518",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/gsd/auto/closeout.ts

@@ -3,8 +3,10 @@
 
 import { importExtensionModule, type ExtensionAPI, type ExtensionContext } from "@gsd/pi-coding-agent";
 
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { join, basename } from "node:path";
-import { existsSync, cpSync } from "node:fs";
+import { existsSync, cpSync, readFileSync } from "node:fs";
 import type { AutoSession } from "./session.js";
 import type { LoopDeps } from "./loop-deps.js";
 import type { GSDState } from "../types.js";
@@ -16,7 +18,7 @@ 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 { gsdRoot } from "../paths.js";
+import { gsdRoot, PLANNING_ARTIFACT_SUFFIXES } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
@@ -98,7 +100,15 @@ export async function _runMilestoneMergeWithStashRestore(
 ): Promise<{ action: "break"; reason: string } | null> {
   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,
     {
@@ -113,12 +123,12 @@ export async function _runMilestoneMergeWithStashRestore(
   );
 
   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") {
@@ -180,10 +190,23 @@ export async function _runMilestoneMergeWithStashRestore(
   return null;
 }
 
-async function markMilestoneMergedAndRebuild(s: AutoSession): Promise<void> {
+type GsdMarkdownSnapshot = Map<string, string>;
+
+async function markMilestoneMergedAndRebuild(
+  s: AutoSession,
+  rebuildBasePath: string,
+  ignoredProjectionSnapshot: GsdMarkdownSnapshot | null,
+): Promise<void> {
   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);
   } catch (err) {
@@ -194,6 +217,90 @@ async function markMilestoneMergedAndRebuild(s: AutoSession): Promise<void> {
   }
 }
 
+function hasDirtyGsdMarkdownProjections(
+  basePath: string,
+  ignoredProjectionSnapshot: GsdMarkdownSnapshot | null,
+): boolean {
+  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: string): boolean {
+  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: string): boolean {
+  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: string): GsdMarkdownSnapshot | null {
+  try {
+    const output = execFileSync(
+      "git",
+      ["ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", ".gsd"],
+      { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const snapshot: GsdMarkdownSnapshot = 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: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function ignoredGsdMarkdownProjectionSnapshotChanged(
+  basePath: string,
+  before: GsdMarkdownSnapshot | null,
+): boolean {
+  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: IterationContext,
   milestoneId: string,

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -34,7 +34,8 @@ 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";
@@ -49,7 +50,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";
@@ -731,7 +732,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return new GitServiceImpl(basePath, gitConfig);
       },
       worktreeProjection: new WorktreeStateProjection(),
-      mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
+      mergeMilestone: createDefaultMilestoneMergeTransaction(),
     });
   }
 

package/src/resources/extensions/gsd/auto/pre-dispatch.ts

@@ -440,7 +440,8 @@ export async function runPreDispatch(
       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();
 
@@ -551,7 +552,8 @@ export async function runPreDispatch(
         // #2909 / #5538-followup: preflight stash + always-on postflight pop.
         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);
@@ -654,7 +656,8 @@ export async function runPreDispatch(
       // #2909 / #5538-followup: preflight stash + always-on postflight pop.
       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",

package/src/resources/extensions/gsd/auto/unit-phase.ts

@@ -29,7 +29,7 @@ import type { MinimalModelRegistry } from "../context-budget.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,
@@ -343,17 +343,13 @@ export async function runUnitPhase(
     ? `${(s.currentUnitModel as any).provider ?? ""}/${(s.currentUnitModel as any).id ?? ""}`
     : null;
 
-  const compatibilityError = getUnitWorkflowDispatchReadinessError({
-    provider: s.currentUnitModel?.provider ?? ctx.model?.provider,
+  const compatibilityError = getUnitWorkflowDispatchReadinessErrorForModel({
+    model: s.currentUnitModel as any,
+    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 as any)?.baseUrl ?? ctx.model?.baseUrl,
     activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
   });
   const workflowMcpPrepModel = s.currentUnitModel;

package/src/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -31,7 +31,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { MinimalModelRegistry } from "./context-budget.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: string): { phase: string; milestoneId?: string } {
   const tokens = raw.trim().split(/\s+/).filter(Boolean);
@@ -266,13 +266,12 @@ export async function dispatchDirectPhase(
       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/src/resources/extensions/gsd/auto-start.ts

@@ -63,9 +63,11 @@ import {
   detectWorktreeName,
   setActiveMilestoneId,
 } from "./worktree.js";
-import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.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/src/resources/extensions/gsd/auto-worktree-branch-lifecycle.ts

@@ -0,0 +1,237 @@
+// 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: string): string {
+  return `milestone/${milestoneId}`;
+}
+
+export function _resolveAutoWorktreeStartPoint(
+  integrationBranch: string | null | undefined,
+  gitMainBranch: string | null | undefined,
+  branchExists: (branch: string) => boolean,
+): string | undefined {
+  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: string,
+  milestoneId: string,
+): void {
+  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: string,
+  branch: string,
+): boolean {
+  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: string,
+  milestoneId: string,
+): string | null {
+  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: string,
+  milestoneId: string,
+  branch: string,
+): void {
+  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),
+    });
+  }
+}