gsd-pi 2.70.1 → 2.71.0-dev.246c32d

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

@@ -6,7 +6,13 @@
  * or AutoContext dependency. State accessors are passed as callbacks.
  */
 
-import type { ExtensionContext, ExtensionCommandContext, SessionMessageEntry } from "@gsd/pi-coding-agent";
+import type {
+  ExtensionContext,
+  ExtensionCommandContext,
+  SessionMessageEntry,
+  ReadonlyFooterDataProvider,
+  Theme,
+} from "@gsd/pi-coding-agent";
 import type { GSDState } from "./types.js";
 import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
@@ -17,7 +23,6 @@ import {
   resolveSliceFile,
 } from "./paths.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { formatShortcut } from "./files.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
@@ -38,6 +43,7 @@ import {
   type RtkSessionSavings,
 } from "../shared/rtk-session-stats.js";
 import { logWarning } from "./workflow-logger.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 
 // ─── UAT Slice Extraction ─────────────────────────────────────────────────────
 
@@ -358,12 +364,23 @@ function getLastCommit(basePath: string): { timeAgo: string; message: string } |
 // ─── Footer Factory ───────────────────────────────────────────────────────────
 
 /**
- * Footer factory that renders zero lines — hides the built-in footer entirely.
- * All footer info (pwd, branch, tokens, cost, model) is shown inside the
- * progress widget instead, so there's no gap or redundancy.
+ * Footer factory used by auto-mode.
+ * Keep footer minimal but preserve extension status context from setStatus().
  */
-export const hideFooter = () => ({
-  render(_width: number): string[] { return []; },
+function sanitizeFooterStatus(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+export const hideFooter = (_tui: unknown, theme: Theme, footerData: ReadonlyFooterDataProvider) => ({
+  render(width: number): string[] {
+    const extensionStatuses = footerData.getExtensionStatuses();
+    if (extensionStatuses.size === 0) return [];
+    const statusLine = Array.from(extensionStatuses.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([, text]) => sanitizeFooterStatus(text))
+      .join(" ");
+    return [truncateToWidth(theme.fg("dim", statusLine), width, theme.fg("dim", "..."))];
+  },
   invalidate() {},
   dispose() {},
 });
@@ -646,14 +663,6 @@ export function updateProgressWidget(
           : "";
         lines.push(rightAlign(headerLeft, headerRight, width));
 
-        // Worktree/branch right-aligned below header
-        const branchLabel = worktreeName && cachedBranch
-          ? `${worktreeName} (${cachedBranch})`
-          : cachedBranch ?? "";
-        if (branchLabel) {
-          lines.push(rightAlign("", theme.fg("dim", branchLabel), width));
-        }
-
         // Show health signal details when degraded (yellow/red)
         if (score.level !== "green" && score.signals.length > 0 && widgetMode !== "min") {
           // Show up to 3 most relevant signals in compact form
@@ -917,15 +926,17 @@ export function updateProgressWidget(
         // Hints line
         const hintParts: string[] = [];
         hintParts.push("esc pause");
-        hintParts.push(`${formatShortcut("Ctrl+Alt+G")} dashboard`);
+        hintParts.push(`${formattedShortcutPair("dashboard")} dashboard`);
+        hintParts.push(`${formattedShortcutPair("parallel")} parallel`);
         const hintStr = theme.fg("dim", hintParts.join(" | "));
         const commitStr = lastCommit
           ? theme.fg("dim", `${lastCommit.timeAgo} ago: ${commitMsg}`)
           : "";
+        const locationStr = theme.fg("dim", widgetPwd);
         if (commitStr) {
-          lines.push(rightAlign(`${pad}${commitStr}`, hintStr, width));
+          lines.push(rightAlign(`${pad}${locationStr} · ${commitStr}`, hintStr, width));
         } else {
-          lines.push(rightAlign("", hintStr, width));
+          lines.push(rightAlign(`${pad}${locationStr}`, hintStr, width));
         }
 
         lines.push(...ui.bar());

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

@@ -14,6 +14,7 @@ import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
 import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet, filterToolsForProvider } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
+import { getSessionModelOverride } from "./session-model-override.js";
 
 export interface ModelSelectionResult {
   /** Routing metadata for metrics recording */
@@ -72,8 +73,15 @@ export async function selectAndApplyModel(
   /** When false (interactive/guided-flow), skip dynamic routing and use the session model.
    *  Dynamic routing only applies in auto-mode where cost optimization is expected. (#3962) */
   isAutoMode = true,
+  /** Explicit /gsd model pin captured at bootstrap for long-running auto loops. */
+  sessionModelOverride?: { provider: string; id: string } | null,
 ): Promise<ModelSelectionResult> {
-  const modelConfig = resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
+  const effectiveSessionModelOverride = sessionModelOverride === undefined
+    ? getSessionModelOverride(ctx.sessionManager.getSessionId())
+    : (sessionModelOverride ?? undefined);
+  const modelConfig = effectiveSessionModelOverride
+    ? undefined
+    : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
   let routing: { tier: string; modelDowngraded: boolean } | null = null;
   let appliedModel: Model<Api> | null = null;
 

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

@@ -24,7 +24,13 @@ import { getLoadedSkills, type Skill } from "@gsd/pi-coding-agent";
 import { join, basename } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary } from "./context-budget.js";
-import { getPendingGates } from "./gsd-db.js";
+import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
+import {
+  GATE_REGISTRY,
+  assertGateCoverage,
+  getGatesForTurn,
+  type GateDefinition,
+} from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
 import { logWarning } from "./workflow-logger.js";
@@ -1395,6 +1401,17 @@ export async function buildExecuteTaskPrompt(
 
   const phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
 
+  // Task-scoped gates owned by execute-task (Q5/Q6/Q7). Pull only the
+  // gates that plan-slice actually seeded for this task — tasks with no
+  // external dependencies legitimately skip Q5, tasks with no runtime
+  // load dimension skip Q6, etc.
+  const etPending = getPendingGatesForTurn(mid, sid, "execute-task", tid);
+  assertGateCoverage(etPending, "execute-task", { requireAll: false });
+  const gatesToClose = renderGatesToCloseBlock(
+    getGatesForTurn("execute-task"),
+    { pending: new Set(etPending.map((g) => g.gate_id)), allowOmit: true },
+  );
+
   return loadPrompt("execute-task", {
     overridesSection,
     runtimeContext,
@@ -1412,6 +1429,7 @@ export async function buildExecuteTaskPrompt(
     taskSummaryPath,
     inlinedTemplates,
     verificationBudget,
+    gatesToClose,
     skillActivation: buildSkillActivationBlock({
       base,
       milestoneId: mid,
@@ -1477,6 +1495,19 @@ export async function buildCompleteSlicePrompt(
   const sliceSummaryPath = join(base, `${sliceRel}/${sid}-SUMMARY.md`);
   const sliceUatPath = join(base, `${sliceRel}/${sid}-UAT.md`);
 
+  // Gates owned by complete-slice (e.g. Q8). Pull from the DB so the
+  // prompt only prompts for gates the plan actually seeded. The tool
+  // handler closes each gate based on the SUMMARY.md section content
+  // after the assistant calls gsd_complete_slice.
+  const csPending = getPendingGatesForTurn(mid, sid, "complete-slice");
+  // coverage check: every pending row must be owned by complete-slice.
+  // requireAll:false because a slice may have already closed some gates.
+  assertGateCoverage(csPending, "complete-slice", { requireAll: false });
+  const gatesToClose = renderGatesToCloseBlock(
+    getGatesForTurn("complete-slice"),
+    { pending: new Set(csPending.map((g) => g.gate_id)), allowOmit: true },
+  );
+
   return loadPrompt("complete-slice", {
     workingDirectory: base,
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
@@ -1485,6 +1516,7 @@ export async function buildCompleteSlicePrompt(
     inlinedContext,
     sliceSummaryPath,
     sliceUatPath,
+    gatesToClose,
   });
 }
 
@@ -1675,6 +1707,16 @@ export async function buildValidateMilestonePrompt(
   const validationOutputPath = join(base, `${relMilestonePath(base, mid)}/${mid}-VALIDATION.md`);
   const roadmapOutputPath = `${relMilestonePath(base, mid)}/${mid}-ROADMAP.md`;
 
+  // Every milestone validation turn owns MV01–MV04 unconditionally: the
+  // registry is the source of truth for which gates the validator must
+  // address, and the block below is what the template renders so the
+  // assistant can never accidentally skip one.
+  const mvGates = getGatesForTurn("validate-milestone");
+  const gatesToEvaluate = renderGatesToCloseBlock(mvGates, {
+    pending: new Set(mvGates.map((g) => g.id)),
+    allowOmit: false,
+  });
+
   return loadPrompt("validate-milestone", {
     workingDirectory: base,
     milestoneId: mid,
@@ -1683,6 +1725,7 @@ export async function buildValidateMilestonePrompt(
     inlinedContext,
     validationPath: validationOutputPath,
     remediationRound: String(remediationRound),
+    gatesToEvaluate,
     skillActivation: buildSkillActivationBlock({
       base,
       milestoneId: mid,
@@ -1955,27 +1998,51 @@ export async function buildReactiveExecutePrompt(
 }
 
 // ─── Gate Evaluation ──────────────────────────────────────────────────────
+//
+// Gate definitions (question, guidance, owner turn) now live in
+// gate-registry.ts so that prompt builders, dispatch rules, state
+// derivation, and tool handlers all consult the same source of truth.
+// See gate-registry.ts for the full ownership map.
 
-const GATE_QUESTIONS: Record<string, { question: string; guidance: string }> = {
-  Q3: {
-    question: "How can this be exploited?",
-    guidance: [
-      "Identify abuse scenarios: parameter tampering, replay attacks, privilege escalation.",
-      "Map data exposure risks: PII, tokens, secrets accessible through this slice.",
-      "Define input trust boundaries: untrusted user input reaching DB, API, or filesystem.",
-      "If none apply, return verdict 'omitted' with rationale explaining why.",
-    ].join("\n"),
-  },
-  Q4: {
-    question: "What existing promises does this break?",
-    guidance: [
-      "List which existing requirements (R001, R003, etc.) are touched by this slice.",
-      "Identify what must be re-tested after shipping.",
-      "Flag decisions that should be revisited given the new scope.",
-      "If no existing requirements are affected, return verdict 'omitted'.",
-    ].join("\n"),
-  },
-};
+/**
+ * Render a "Gates to Close" block for turns like `complete-slice` and
+ * `validate-milestone` that own gates which are closed as a side-effect
+ * of writing artifact sections (not via a dedicated gate-evaluate
+ * subagent loop).
+ *
+ * Returns a plain-text block or an empty string if there are no gates to
+ * close, so callers can drop it straight into a template variable.
+ */
+function renderGatesToCloseBlock(
+  gates: ReadonlyArray<GateDefinition>,
+  opts: { pending: ReadonlySet<string>; allowOmit: boolean },
+): string {
+  const applicable = gates.filter((g) => opts.pending.has(g.id));
+  if (applicable.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push("## Gates to Close");
+  lines.push("");
+  lines.push(
+    "These quality gates are still pending for this unit. You MUST address every one before calling the closing tool — the handler closes the DB row based on whether the corresponding artifact section is present.",
+  );
+  lines.push("");
+  for (const def of applicable) {
+    lines.push(`### ${def.id} — ${def.promptSection}`);
+    lines.push("");
+    lines.push(`**Question:** ${def.question}`);
+    lines.push("");
+    lines.push(def.guidance);
+    if (opts.allowOmit) {
+      lines.push("");
+      lines.push(
+        `If this gate genuinely does not apply to this unit, leave the **${def.promptSection}** section empty and the handler will record it as \`omitted\`. Otherwise, fill the section with concrete evidence.`,
+      );
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
 
 export async function buildParallelResearchSlicesPrompt(
   mid: string,
@@ -2011,28 +2078,39 @@ export async function buildGateEvaluatePrompt(
   mid: string, midTitle: string, sid: string, sTitle: string,
   base: string,
 ): Promise<string> {
-  const pending = getPendingGates(mid, sid, "slice");
+  // Pull only the gates this turn actually owns (Q3/Q4). Filter via the
+  // registry so that scope:"slice" gates owned by other turns (Q8) can't
+  // leak into this prompt and can't block dispatch via silent skip.
+  const pending = getPendingGatesForTurn(mid, sid, "gate-evaluate");
+
+  // Fails loudly if the pending list contains a gate id the registry
+  // doesn't own for this turn. Missing owned gates is allowed here —
+  // `gate-evaluate` is dispatched whenever *any* of its owned gates are
+  // pending, not only when all of them are.
+  assertGateCoverage(pending, "gate-evaluate", { requireAll: false });
 
   // Load the slice plan for context
   const planFile = resolveSliceFile(base, mid, sid, "PLAN");
   const planContent = planFile ? (await loadFile(planFile)) ?? "(plan file empty)" : "(plan file not found)";
 
-  // Build per-gate subagent prompts
+  // Build per-gate subagent prompts from the pending rows. Because the
+  // registry has already validated every row, `getGateDefinition` cannot
+  // return undefined here.
+  const pendingIds = new Set(pending.map((g) => g.gate_id));
+  const gateDefs = getGatesForTurn("gate-evaluate").filter((def) => pendingIds.has(def.id));
+
   const subagentSections: string[] = [];
   const gateListLines: string[] = [];
 
-  for (const gate of pending) {
-    const meta = GATE_QUESTIONS[gate.gate_id];
-    if (!meta) continue;
-
-    gateListLines.push(`- **${gate.gate_id}**: ${meta.question}`);
+  for (const def of gateDefs) {
+    gateListLines.push(`- **${def.id}**: ${def.question}`);
 
     const subPrompt = [
-      `You are evaluating quality gate **${gate.gate_id}** for slice ${sid} (${sTitle}).`,
+      `You are evaluating quality gate **${def.id}** for slice ${sid} (${sTitle}).`,
       "",
-      `## Question: ${meta.question}`,
+      `## Question: ${def.question}`,
       "",
-      meta.guidance,
+      def.guidance,
       "",
       "## Slice Plan",
       "",
@@ -2044,14 +2122,14 @@ export async function buildGateEvaluatePrompt(
       `Call the \`gsd_save_gate_result\` tool with:`,
       `- \`milestoneId\`: "${mid}"`,
       `- \`sliceId\`: "${sid}"`,
-      `- \`gateId\`: "${gate.gate_id}"`,
+      `- \`gateId\`: "${def.id}"`,
       "- `verdict`: \"pass\" (no concerns), \"flag\" (concerns found), or \"omitted\" (not applicable)",
       "- `rationale`: one-sentence justification",
       "- `findings`: detailed markdown findings (or empty if omitted)",
     ].join("\n");
 
     subagentSections.push([
-      `### ${gate.gate_id}: ${meta.question}`,
+      `### ${def.id}: ${def.question}`,
       "",
       "Use this as the prompt for a `subagent` call:",
       "",

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

@@ -85,6 +85,7 @@ import { sep as pathSep } from "node:path";
 import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
 import { resolveDefaultSessionModel, resolveDynamicRoutingConfig } from "./preferences-models.js";
 import type { WorktreeResolver } from "./worktree-resolver.js";
+import { getSessionModelOverride } from "./session-model-override.js";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -266,13 +267,42 @@ export async function bootstrapAutoSession(
   // Capture the user's session model before guided-flow dispatch can apply a
   // phase-specific planning model for a discuss turn (#2829).
   //
-  // GSD PREFERENCES.md takes priority over the session model from settings.json
-  // (#3517).  The session model (ctx.model) comes from findInitialModel() which
-  // reads defaultProvider/defaultModel from ~/.gsd/agent/settings.json.  When
-  // the user has explicit model preferences in PREFERENCES.md, those should win.
+  // Precedence:
+  // 1) Explicit session override via /gsd model (this session)
+  // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
+  // 3) Current session model from settings/session restore (if provider ready)
+  //
+  // This preserves #3517 defaults while honoring explicit runtime model
+  // selection for subsequent /gsd runs in the same session.
+  const manualSessionOverride = getSessionModelOverride(ctx.sessionManager.getSessionId());
   const preferredModel = resolveDefaultSessionModel(ctx.model?.provider);
-  const startModelSnapshot = preferredModel
-    ?? (ctx.model
+  // Validate the preferred model against the live registry + provider auth so
+  // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
+  // start-model snapshot. Without this, every subsequent unit would try to
+  // fall back to an unusable model.
+  let validatedPreferredModel: { provider: string; id: string } | undefined;
+  if (preferredModel) {
+    const { resolveModelId } = await import("./auto-model-selection.js");
+    const available = ctx.modelRegistry.getAvailable();
+    const match = resolveModelId(
+      `${preferredModel.provider}/${preferredModel.id}`,
+      available,
+      ctx.model?.provider,
+    );
+    if (match) {
+      validatedPreferredModel = { provider: match.provider, id: match.id };
+    } else {
+      ctx.ui.notify(
+        `Preferred model ${preferredModel.provider}/${preferredModel.id} from PREFERENCES.md is not configured; falling back to session default.`,
+        "warning",
+      );
+    }
+  }
+  const sessionModelReady =
+    ctx.model && ctx.modelRegistry.isProviderRequestReady(ctx.model.provider);
+  const startModelSnapshot = manualSessionOverride
+    ?? validatedPreferredModel
+    ?? (sessionModelReady && ctx.model
       ? { provider: ctx.model.provider, id: ctx.model.id }
       : null);
 
@@ -335,19 +365,9 @@ export async function bootstrapAutoSession(
       }
     }
 
-    if (ctx.model?.provider === "claude-code") {
-      try {
-        const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
-        const result = ensureProjectWorkflowMcpConfig(base);
-        if (result.status !== "unchanged") {
-          ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-      }
+    {
+      const { prepareWorkflowMcpForProject } = await import("./workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, base);
     }
 
     // Initialize GitServiceImpl
@@ -604,6 +624,9 @@ export async function bootstrapAutoSession(
     s.consecutiveCompleteBootstraps = 0;
 
     // ── Initialize session state ──
+    // Notify shared phase state so subagent conflict checks can fire
+    const { activateGSD: activateGSDPhaseState } = await import("../shared/gsd-phase-state.js");
+    activateGSDPhaseState();
     s.active = true;
     s.stepMode = requestedStepMode;
     s.verbose = verboseMode;
@@ -688,7 +711,7 @@ export async function bootstrapAutoSession(
     }
 
     // ── DB lifecycle ──
-    const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
+    const gsdDbPath = resolveProjectRootDbPath(s.basePath);
     const gsdDirPath = join(s.basePath, ".gsd");
     if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
       const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
@@ -741,6 +764,7 @@ export async function bootstrapAutoSession(
         id: startModelSnapshot.id,
       };
     }
+    s.manualSessionModelOverride = manualSessionOverride ?? null;
 
     // Apply worker model override from parallel orchestrator (#worker-model).
     // GSD_WORKER_MODEL is injected by the coordinator when parallel.worker_model

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -92,7 +92,7 @@ export function clearInFlightTools(): void {
  * handler. When these errors occur, retrying the same unit will produce the same
  * failure, so the retry loop must be broken.
  */
-const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}' in JSON|Unexpected end of JSON|Unexpected token.*in JSON/i;
+const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON/i;
 
 /**
  * Returns true if the error message indicates a tool invocation failure due to

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

@@ -2043,7 +2043,7 @@ export function mergeMilestoneToMain(
   // 12. Remove worktree directory first (must happen before branch deletion)
   try {
     removeWorktree(originalBasePath_, milestoneId, {
-      branch: null as unknown as string,
+      branch: milestoneBranch,
       deleteBranch: false,
     });
   } catch (err) {

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

@@ -115,6 +115,7 @@ import {
   resetSkillTelemetry,
 } from "./skill-telemetry.js";
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
+import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import {
   initMetrics,
   resetMetrics,
@@ -165,6 +166,7 @@ import {
   reconcileMergeState,
 } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
+import { getErrorMessage } from "./error-utils.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
 import {
@@ -272,6 +274,53 @@ function restoreProjectRootEnv(): void {
   s.projectRootEnvCaptured = false;
 }
 
+function captureMilestoneLockEnv(milestoneId: string | null): void {
+  if (!s.milestoneLockEnvCaptured) {
+    s.hadMilestoneLockEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_MILESTONE_LOCK");
+    s.previousMilestoneLockEnv = process.env.GSD_MILESTONE_LOCK ?? null;
+    s.milestoneLockEnvCaptured = true;
+  }
+
+  if (milestoneId) {
+    process.env.GSD_MILESTONE_LOCK = milestoneId;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+}
+
+function restoreMilestoneLockEnv(): void {
+  if (!s.milestoneLockEnvCaptured) return;
+
+  if (s.hadMilestoneLockEnv && s.previousMilestoneLockEnv !== null) {
+    process.env.GSD_MILESTONE_LOCK = s.previousMilestoneLockEnv;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+
+  s.previousMilestoneLockEnv = null;
+  s.hadMilestoneLockEnv = false;
+  s.milestoneLockEnvCaptured = false;
+}
+
+export function startAutoDetached(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  base: string,
+  verboseMode: boolean,
+  options?: {
+    step?: boolean;
+    interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
+  },
+): void {
+  void startAuto(ctx, pi, base, verboseMode, options).catch((err) => {
+    const message = getErrorMessage(err);
+    ctx.ui.notify(`Auto-start failed: ${message}`, "error");
+    logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
+    debugLog("auto-start-failed", { error: message });
+  });
+}
+
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -549,11 +598,13 @@ function buildSnapshotOpts(
   _unitType: string,
   _unitId: string,
 ): {
+  autoSessionKey?: string;
   continueHereFired?: boolean;
   promptCharCount?: number;
   baselineCharCount?: number;
 } & Record<string, unknown> {
   return {
+    ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
     promptCharCount: s.lastPromptCharCount,
     baselineCharCount: s.lastBaselineCharCount,
     ...(s.currentUnitRouting ?? {}),
@@ -572,8 +623,10 @@ function handleLostSessionLock(
   });
   s.active = false;
   s.paused = false;
+  deactivateGSD();
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   deregisterSigtermHandler();
   clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
   const base = lockBase();
@@ -608,8 +661,10 @@ function handleLostSessionLock(
 function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.currentUnit = null;
   s.active = false;
+  deactivateGSD();
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
 
   // Clear crash lock and release session lock so the next `/gsd next` does
   // not see a stale lock with the current PID and treat it as a "remote"
@@ -880,6 +935,7 @@ export async function stopAuto(
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
     restoreProjectRootEnv();
+    restoreMilestoneLockEnv();
 
     // Reset all session state in one call
     s.reset();
@@ -933,6 +989,7 @@ export async function pauseAuto(
       activeEngineId: s.activeEngineId,
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
+      milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
     mkdirSync(runtimeDir, { recursive: true });
@@ -970,7 +1027,9 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  deactivateGSD();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   s.pendingVerificationRetry = null;
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
@@ -1154,6 +1213,7 @@ export async function startAuto(
   options?: {
     step?: boolean;
     interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
   },
 ): Promise<void> {
   if (s.active) {
@@ -1163,6 +1223,12 @@ export async function startAuto(
 
   const requestedStepMode = options?.step ?? false;
   const interruptedAssessment = options?.interrupted ?? null;
+  if (options?.milestoneLock !== undefined) {
+    s.sessionMilestoneLock = options.milestoneLock ?? null;
+  }
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
 
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
@@ -1194,6 +1260,7 @@ export async function startAuto(
         s.originalBasePath = meta.originalBasePath || base;
         s.stepMode = meta.stepMode ?? requestedStepMode;
         s.autoStartTime = meta.autoStartTime || Date.now();
+        s.sessionMilestoneLock = meta.milestoneLock ?? null;
         s.paused = true;
         try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
         ctx.ui.notify(
@@ -1228,6 +1295,7 @@ export async function startAuto(
             s.pausedUnitType = meta.unitType ?? null;
             s.pausedUnitId = meta.unitId ?? null;
             s.autoStartTime = meta.autoStartTime || Date.now();
+            s.sessionMilestoneLock = meta.milestoneLock ?? null;
             s.paused = true;
             try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
             ctx.ui.notify(
@@ -1247,6 +1315,10 @@ export async function startAuto(
     if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now();
   }
 
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
+
   if (!s.paused) {
     s.stepMode = requestedStepMode;
   }