@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -14,6 +14,7 @@
 
 import type { GSDState, TaskIO } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
+import { renderLanguageDirectiveForPrompt } from "./preferences.js";
 import type { MinimalModelRegistry } from "./context-budget.js";
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
 import { getUatBrowserToolSupportError, type UatType } from "./uat-policy.js";
@@ -838,7 +839,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     },
   },
   {
-    name: "uat-verdict-gate (non-PASS blocks progression)",
+    name: "uat-verdict-gate (non-PASS observed; closeout enforces)",
     match: async ({ mid, basePath, prefs }) => {
       // Only applies when UAT dispatch is enabled
       if (!prefs?.uat_dispatch) return null;
@@ -852,9 +853,9 @@ export const DISPATCH_RULES: DispatchRule[] = [
         const { verdict, uatType } = result;
 
         if (!isAcceptableUatVerdict(verdict, uatType)) {
-          // Do not hard-stop auto-mode on non-PASS verdicts. Allow progression
-          // so follow-up slices can remediate, while complete-milestone still
-          // enforces manual UAT PASS sign-off before closure.
+          // Observe non-PASS verdicts without hard-stopping auto-mode. Allow
+          // progression so follow-up slices can remediate, while
+          // complete-milestone still enforces manual UAT PASS sign-off before closure.
           continue;
         }
       }
@@ -1130,9 +1131,21 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // call site.
       const sliceContextFile = resolveSliceFile(basePath, mid, state.activeSlice.id, "CONTEXT");
       if (sliceContextFile && existsSync(sliceContextFile)) return null; // discussion already done, proceed
+
+      const closedSliceIds = getClosedSliceIds(mid);
+      const justClosedSliceId = closedSliceIds[closedSliceIds.length - 1];
+      let priorVerdictWarning = "";
+      if (justClosedSliceId) {
+        const prior = await readUatGateVerdict(basePath, mid, justClosedSliceId);
+        if (prior && !isAcceptableUatVerdict(prior.verdict, prior.uatType)) {
+          priorVerdictWarning =
+            ` Note: the slice just closed (${justClosedSliceId}) recorded a non-PASS UAT verdict (${prior.verdict.toUpperCase()}); review before continuing.`;
+        }
+      }
+
       return {
         action: "stop" as const,
-        reason: `Slice ${state.activeSlice.id} requires discussion before planning (require_slice_discussion is enabled). Run /gsd discuss to discuss this slice, then /gsd auto to resume.`,
+        reason: `Slice ${state.activeSlice.id} requires discussion before planning (require_slice_discussion is enabled). Run /gsd discuss to discuss this slice, then /gsd auto to resume.${priorVerdictWarning}`,
         level: "warning" as const,
       };
     },
@@ -1822,6 +1835,21 @@ export const DISPATCH_RULES: DispatchRule[] = [
 
 import { getRegistry } from "./rule-registry.js";
 
+/**
+ * Prepend the configured response-language directive to a dispatched unit
+ * prompt so auto-execution units respond in the language set in PREFERENCES.md
+ * (#1210). No-op for non-dispatch actions or when no language is configured.
+ */
+function applyLanguageDirectiveToDispatch(
+  action: DispatchAction,
+  prefs: GSDPreferences | undefined,
+): DispatchAction {
+  if (action.action !== "dispatch" || !action.prompt) return action;
+  const directive = renderLanguageDirectiveForPrompt(prefs);
+  if (!directive) return action;
+  return { ...action, prompt: `${directive}\n\n${action.prompt}` };
+}
+
 // ─── Resolver ─────────────────────────────────────────────────────────────
 
 /**
@@ -1884,7 +1912,7 @@ export async function resolveDispatch(
         level: "error",
       };
     }
-    return action;
+    return applyLanguageDirectiveToDispatch(action, ctx.prefs);
   } catch (err) {
     // Registry not initialized — fall back to inline loop
     logWarning("dispatch", `registry dispatch failed, falling back to inline rules: ${err instanceof Error ? err.message : String(err)}`);
@@ -1906,7 +1934,7 @@ export async function resolveDispatch(
           matchedRule: rule.name,
         };
       }
-      return action;
+      return applyLanguageDirectiveToDispatch(action, ctx.prefs);
     }
   }
 

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -409,7 +409,13 @@ export function resolvePreferredModelConfig(
   availableModelIds?: string[],
   preferredModelId?: string,
 ): PreferredModelConfig | undefined {
-  const explicitConfig = resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds, preferredModelId);
+  const explicitConfig = resolveModelWithFallbacksForUnit(
+    unitType,
+    basePath,
+    availableModelIds,
+    preferredModelId,
+    true,
+  );
   if (explicitConfig) {
     return {
       ...explicitConfig,
@@ -422,26 +428,55 @@ export function resolvePreferredModelConfig(
   if (!isAutoMode) return undefined;
 
   const routingConfig = resolveDynamicRoutingConfig();
-  if (!routingConfig.enabled || !routingConfig.tier_models) return undefined;
+  if (!routingConfig.enabled) return undefined;
 
-  // Don't synthesize a routing config for flat-rate providers (#3453).
-  // Users can opt into routing for flat-rate subscriptions (e.g. claude-code)
-  // via dynamic_routing.allow_flat_rate_providers (#4386).
+  // Only an explicit flat-rate opt-out suppresses synthesized routing.
+  // `dynamic_routing.enabled: true` is user intent to run routing even when
+  // the start provider is a flat-rate subscription. Applied ahead of both the
+  // tier-pin and profile-derived synthesis paths so the opt-out is uniform.
   if (
-    !routingConfig.allow_flat_rate_providers &&
+    routingConfig.allow_flat_rate_providers === false &&
     autoModeStartModel &&
     isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx)
   ) {
     return undefined;
   }
 
-  const ceilingModel = routingConfig.tier_models.heavy
-    ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
-  if (!ceilingModel) return undefined;
+  // With explicit `tier_models` pins, synthesize a heavy-tier ceiling that
+  // dynamic routing downgrades from per unit.
+  if (routingConfig.tier_models) {
+    const ceilingModel = routingConfig.tier_models.heavy
+      ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
+    if (!ceilingModel) return undefined;
+
+    return {
+      primary: ceilingModel,
+      fallbacks: [],
+      source: "synthesized",
+    };
+  }
+
+  // No `tier_models` pins: fall back to the token-profile's per-phase model so
+  // profile tier resolution survives. `skipProfileDefaults` is left false here
+  // (unlike the explicit-detection call above) precisely because we WANT the
+  // profile defaults this time — they are the routing ceiling, not a hard
+  // user selection. Labeling the result `synthesized` (not `explicit`) keeps
+  // dynamic routing and fallbacks enabled downstream. Without this branch,
+  // `resolvePreferredModelConfig` returns undefined for profile-only configs
+  // and auto dispatch bleeds the start model onto every unit, silently
+  // discarding the profile (#1115: routing/fallbacks disabled when a
+  // token_profile is set but no tier_models are pinned).
+  const profileConfig = resolveModelWithFallbacksForUnit(
+    unitType,
+    basePath,
+    availableModelIds,
+    preferredModelId,
+    false,
+  );
+  if (!profileConfig) return undefined;
 
   return {
-    primary: ceilingModel,
-    fallbacks: [],
+    ...profileConfig,
     source: "synthesized",
   };
 }
@@ -647,15 +682,11 @@ export async function selectAndApplyModel(
       }
     }
 
-    // Disable routing for flat-rate providers like GitHub Copilot (#3453).
-    // All models cost the same per request, so downgrading to a cheaper
-    // model provides no cost benefit — it only degrades quality.
+    // Disable routing for flat-rate providers only when the user explicitly
+    // opts out with dynamic_routing.allow_flat_rate_providers: false.
     // Fail-closed: if primary model can't be resolved, fall back to
     // provider-level signals rather than allowing unwanted downgrades.
-    // Opt-in: dynamic_routing.allow_flat_rate_providers skips the bypass so
-    // claude-code subscribers can still get intelligent per-task selection
-    // across their subscription (#4386).
-    if (routingConfig.enabled && !routingConfig.allow_flat_rate_providers) {
+    if (routingConfig.enabled && routingConfig.allow_flat_rate_providers === false) {
       const primaryModel = resolveModelId(modelConfig.primary, routingEligibleModels, ctx.model?.provider);
       if (primaryModel) {
         const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -20,14 +20,15 @@ import {
   relTaskFile, resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
 } from "./paths.js";
 import { resolveInlineLevel, loadEffectiveGSDPreferences } from "./preferences.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
 import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
-import { join, basename, relative } from "node:path";
+import { join, basename, relative, sep } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
-import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
+import { getGateResults, getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
 import {
   GATE_REGISTRY,
   assertGateCoverage,
@@ -393,6 +394,37 @@ function formatExecutorConstraints(
   ].join("\n");
 }
 
+/**
+ * Builds the Declared Repositories block for parent-workspace planners.
+ * Returns "" for single-repo projects so the common-case prompt is unchanged;
+ * only parent mode with declared child repos gets the registry list and the
+ * targetRepositories assignment instruction.
+ */
+export function buildRepoRegistryBlock(base: string): string {
+  let registry;
+  try {
+    registry = createRepositoryRegistryFromPreferences(base, loadEffectiveGSDPreferences(base)?.preferences);
+  } catch {
+    return "";
+  }
+  const hasChildRepo = registry.repositories.some((repo) => repo.id !== "project");
+  if (registry.mode !== "parent" || !hasChildRepo) return "";
+
+  const lines = registry.repositories.map((repo) => {
+    const relPath = relative(registry.projectRoot, repo.root).split(sep).join("/") || ".";
+    const role = repo.role ? ` — ${repo.role}` : "";
+    const root = repo.id === "project" ? " (root)" : ` (${relPath})`;
+    return `- \`${repo.id}\`${root}${role}`;
+  });
+  return [
+    "### Declared Repositories",
+    "",
+    ...lines,
+    "",
+    "This is a parent workspace. Assign each task's `targetRepositories` to the repository id(s) it touches (from the list above). Omit `targetRepositories` to inherit the slice-wide default from `gsd_plan_slice`; set it explicitly when a task differs (e.g. `[\"project\"]` for parent-root work).",
+  ].join("\n");
+}
+
 /**
  * Returns a markdown bullet list of known context file paths for the given
  * milestone (and optionally slice). Falls back to a generic tool-agnostic
@@ -2504,6 +2536,7 @@ async function renderSlicePrompt(options: {
     inlinedContext,
     dependencySummaries: depContent,
     sourceFilePaths: buildSourceFilePaths(base, mid, sid),
+    repoRegistry: buildRepoRegistryBlock(base),
     executorContextConstraints,
     commitInstruction,
     skillActivation: buildSkillActivationBlock({
@@ -3362,6 +3395,44 @@ export async function buildValidateMilestonePrompt(
     trackPromptContext(contextTelemetry, "outstanding-items", "inline", outstandingBlock);
   }
 
+  const persistedGateFlags: string[] = [];
+  try {
+    const gateLabels = {
+      Q3: "Threat Surface",
+      Q4: "Requirement Impact",
+    } as const;
+    for (const sid of seenValSlices) {
+      for (const gate of getGateResults(mid, sid, "slice")) {
+        if (gate.gate_id !== "Q3" && gate.gate_id !== "Q4") continue;
+        const findings = gate.findings.trim();
+        const rationale = gate.rationale.trim();
+        const verdict = gate.verdict ?? "";
+        const hasNonPassVerdict = verdict !== "" && verdict !== "pass" && verdict !== "omitted";
+        if (!findings && !hasNonPassVerdict) continue;
+
+        const displayVerdict = verdict || gate.status;
+        const detail = findings || rationale || "_No findings text recorded; reconcile the persisted non-pass verdict._";
+        persistedGateFlags.push(`- **${sid} / ${gate.gate_id} (${gateLabels[gate.gate_id]}) / ${displayVerdict}:** ${detail}`);
+        if (findings && rationale) persistedGateFlags.push(`  - Rationale: ${rationale}`);
+      }
+    }
+  } catch (err) {
+    logWarning("prompt", `buildValidateMilestonePrompt persisted gate flags lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (persistedGateFlags.length > 0) {
+    const persistedGateFlagsBlock = [
+      "### Persisted Slice-Level Gate Flags (from quality_gates)",
+      "",
+      "These slice gates recorded findings or non-pass verdicts during execution. Reconcile each against the milestone-level evidence before returning MV03/MV04 verdicts.",
+      "",
+      ...persistedGateFlags,
+    ].join("\n");
+    inlined.push(persistedGateFlagsBlock);
+    trackPromptContext(contextTelemetry, "persisted-slice-gate-flags", "inline", persistedGateFlagsBlock);
+  } else {
+    trackPromptContext(contextTelemetry, "persisted-slice-gate-flags", "skipped", null, "none");
+  }
+
   // Inline existing VALIDATION file if this is a re-validation round
   const validationPath = resolveMilestoneFile(base, mid, "VALIDATION");
   const validationRel = relMilestoneFile(base, mid, "VALIDATION");

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -234,12 +234,56 @@ export function refreshRecoveryDbForArtifact(
   }
 
   if (!isClosedStatus(task.status)) {
-    return {
-      ok: false,
-      fatal: true,
-      reason: "execute-task-artifact-db-mismatch",
-      message: `Stuck recovery found execute-task ${unitId} artifacts, but the DB task status is still '${task.status}' after refresh.`,
-    };
+    // The artifact was already confirmed on disk by verifyExpectedArtifact
+    // upstream (Gate 1 accepts a checked disk checkbox as proof of completion),
+    // but the DB task row is still open. A bare refreshWorkflowDatabaseFromDisk
+    // never promotes the disk checkbox into task status (the checkbox is
+    // rendered *from* the DB, never *into* it), so this divergence can never
+    // self-heal. Promote the task to align the DB with disk instead of failing
+    // shut — otherwise the lowest-pending derivation re-picks the same task
+    // forever and execute-task hard-stops with "state did not advance" (#1204).
+    // Mirrors the promotion pattern used by the context-exhaustion and
+    // reactive-execute-blocker recovery paths.
+    const ts = new Date().toISOString();
+    // Only the DB promotion is load-bearing: if it throws, nothing advanced
+    // and failing shut is correct. The plan checkbox rewrite and cache clears
+    // are best-effort follow-ups — a throw there must NOT abort recovery, or
+    // the DB is left complete without ever emitting the stuck-artifact-recovery
+    // event (#1221), stranding worktree reconciliation.
+    try {
+      updateTaskStatus(mid, sid, tid, "complete", ts);
+    } catch (e) {
+      return {
+        ok: false,
+        fatal: true,
+        reason: "execute-task-artifact-db-promote-failed",
+        message: `Stuck recovery found execute-task ${unitId} artifacts, but promoting the DB task status from '${task.status}' failed: ${getErrorMessage(e)}`,
+      };
+    }
+    try {
+      const artifactBase = resolveArtifactVerificationBase(unitId, basePath);
+      const planPath = resolveExpectedArtifactPath("plan-slice", `${mid}/${sid}`, artifactBase);
+      if (planPath && existsSync(planPath)) {
+        const planContent = readFileSync(planPath, "utf-8");
+        const updatedPlan = planContent.replace(
+          new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
+          `$1[x] **${tid}:`,
+        );
+        if (updatedPlan !== planContent) {
+          atomicWriteSync(planPath, updatedPlan);
+        }
+      }
+      clearPathCache();
+      clearParseCache();
+    } catch (e) {
+      logWarning("recovery", `stuck-artifact plan checkbox sync failed after DB promotion of ${unitId}: ${getErrorMessage(e)}`);
+    }
+    // Append event so worktree reconciliation can replay this recovery completion.
+    try {
+      appendEvent(basePath, { cmd: "complete-task", params: { milestoneId: mid, sliceId: sid, taskId: tid }, ts, actor: "system", trigger_reason: "stuck-artifact-recovery" });
+    } catch (e) {
+      logWarning("recovery", `appendEvent failed for stuck-artifact task promotion: ${getErrorMessage(e)}`);
+    }
   }
 
   return { ok: true };

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";
@@ -1813,7 +1815,7 @@ export async function bootstrapAutoSession(
 
     // Snapshot installed skills
     if (resolveSkillDiscoveryMode(base) !== "off") {
-      snapshotSkills();
+      snapshotSkills({ cwd: s.basePath });
     }
 
     setAutoActiveStatus(ctx, s.stepMode ? "next" : "auto");
@@ -1849,8 +1851,9 @@ export async function bootstrapAutoSession(
       : ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "default";
 
     // Flat-rate providers (e.g. GitHub Copilot, claude-code, user-declared
-    // subscription proxies, externalCli CLIs) suppress routing at dispatch
-    // time (#3453) — reflect that in the banner.  Thread the same
+    // subscription proxies, externalCli CLIs) suppress routing only when the
+    // user explicitly opts out with allow_flat_rate_providers: false. Reflect
+    // that in the banner. Thread the same
     // FlatRateContext used by selectAndApplyModel so user-declared
     // flat-rate providers and externalCli auto-detection are respected.
     const { isFlatRateProvider, buildFlatRateContext } = await import("./auto-model-selection.js");
@@ -1862,7 +1865,7 @@ export async function bootstrapAutoSession(
     )?.preferences;
     const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
     const effectivelyEnabled = routingConfig.enabled
-      && (routingConfig.allow_flat_rate_providers
+      && (routingConfig.allow_flat_rate_providers !== false
         || !(effectiveProvider && isFlatRateProvider(
           effectiveProvider,
           buildFlatRateContext(effectiveProvider, ctx, bannerPrefs),

package/src/resources/extensions/gsd/auto-timeout-recovery.ts

@@ -97,6 +97,8 @@ export async function recoverTimedOutUnit(
         lastProgressAt: Date.now(),
         progressCount: (runtime?.progressCount ?? 0) + 1,
         lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
+        // This steering retry is a fresh chance for the same unit to save a valid result.
+        harnessAbort: undefined,
       });
 
       const steeringLines = isEscalation
@@ -222,6 +224,8 @@ export async function recoverTimedOutUnit(
       lastProgressAt: Date.now(),
       progressCount: (runtime?.progressCount ?? 0) + 1,
       lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
+      // This steering retry is a fresh chance for the same unit to save a valid result.
+      harnessAbort: undefined,
     });
 
     const steeringLines = isEscalation

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),
+    });
+  }
+}