gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -2,14 +2,51 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js";
-import { getNextFallbackModel, isTransientNetworkError, resolveModelWithFallbacksForUnit } from "../preferences.js";
-import { classifyProviderError, pauseAutoForProviderError } from "../provider-error-pause.js";
+import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
+import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
+import { resolveModelId } from "../auto-model-selection.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
+import {
+  classifyError,
+  createRetryState,
+  resetRetryState,
+  isTransient,
+  type ErrorClass,
+} from "../error-classifier.js";
 
-const networkRetryCounters = new Map<string, number>();
+const retryState = createRetryState();
+const MAX_NETWORK_RETRIES = 2;
 const MAX_TRANSIENT_AUTO_RESUMES = 3;
-let consecutiveTransientErrors = 0;
+
+async function pauseTransientWithBackoff(
+  cls: ErrorClass,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  errorDetail: string,
+  isRateLimit: boolean,
+): Promise<void> {
+  retryState.consecutiveTransientCount += 1;
+  const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
+  const retryAfterMs = baseRetryAfterMs * 2 ** Math.max(0, retryState.consecutiveTransientCount - 1);
+  const allowAutoResume = retryState.consecutiveTransientCount <= MAX_TRANSIENT_AUTO_RESUMES;
+  if (!allowAutoResume) {
+    ctx.ui.notify(`Transient provider errors persisted after ${MAX_TRANSIENT_AUTO_RESUMES} auto-resume attempts. Pausing for manual review.`, "warning");
+  }
+  await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi), {
+    isRateLimit,
+    isTransient: allowAutoResume,
+    retryAfterMs,
+    resume: allowAutoResume
+      ? () => {
+        pi.sendMessage(
+          { customType: "gsd-auto-timeout-recovery", content: "Continue execution — provider error recovery delay elapsed.", display: false },
+          { triggerTurn: true },
+        );
+      }
+      : undefined,
+  });
+}
 
 export async function handleAgentEnd(
   pi: ExtensionAPI,
@@ -31,17 +68,26 @@ export async function handleAgentEnd(
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
     const errorDetail = "errorMessage" in lastMsg && lastMsg.errorMessage ? `: ${lastMsg.errorMessage}` : "";
     const errorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+    const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
 
-    if (isTransientNetworkError(errorMsg)) {
+    // ── 1. Classify ──────────────────────────────────────────────────────
+    const cls = classifyError(errorMsg, explicitRetryAfterMs);
+
+    // ── 2. Decide & Act ──────────────────────────────────────────────────
+
+    // --- Network errors: same-model retry with backoff ---
+    if (cls.kind === "network") {
       const currentModelId = ctx.model?.id ?? "unknown";
-      const retryKey = `network-retry:${currentModelId}`;
-      const currentRetries = networkRetryCounters.get(retryKey) ?? 0;
-      const maxRetries = 2;
-      if (currentRetries < maxRetries) {
-        networkRetryCounters.set(retryKey, currentRetries + 1);
-        const attempt = currentRetries + 1;
-        const delayMs = attempt * 3000;
-        ctx.ui.notify(`Network error on ${currentModelId}${errorDetail}. Retry ${attempt}/${maxRetries} in ${delayMs / 1000}s...`, "warning");
+      if (retryState.currentRetryModelId !== currentModelId) {
+        retryState.networkRetryCount = 0;
+        retryState.currentRetryModelId = currentModelId;
+      }
+      if (retryState.networkRetryCount < MAX_NETWORK_RETRIES) {
+        retryState.networkRetryCount += 1;
+        retryState.consecutiveTransientCount += 1;
+        const attempt = retryState.networkRetryCount;
+        const delayMs = attempt * cls.retryAfterMs;
+        ctx.ui.notify(`Network error on ${currentModelId}${errorDetail}. Retry ${attempt}/${MAX_NETWORK_RETRIES} in ${delayMs / 1000}s...`, "warning");
         setTimeout(() => {
           pi.sendMessage(
             { customType: "gsd-auto-timeout-recovery", content: "Continue execution — retrying after transient network error.", display: false },
@@ -50,84 +96,82 @@ export async function handleAgentEnd(
         }, delayMs);
         return;
       }
-      networkRetryCounters.delete(retryKey);
+      // Network retries exhausted — fall through to model fallback
+      retryState.networkRetryCount = 0;
+      retryState.currentRetryModelId = undefined;
       ctx.ui.notify(`Network retries exhausted for ${currentModelId}. Attempting model fallback.`, "warning");
     }
 
-    const dash = getAutoDashboardData();
-    if (dash.currentUnit) {
-      const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
-      if (modelConfig && modelConfig.fallbacks.length > 0) {
-        const availableModels = ctx.modelRegistry.getAvailable();
-        const nextModelId = getNextFallbackModel(ctx.model?.id, modelConfig);
-        if (nextModelId) {
-          networkRetryCounters.clear();
-          const slashIdx = nextModelId.indexOf("/");
-          const modelToSet = slashIdx !== -1
-            ? availableModels.find((m) => m.provider.toLowerCase() === nextModelId.substring(0, slashIdx).toLowerCase() && m.id.toLowerCase() === nextModelId.substring(slashIdx + 1).toLowerCase())
-            : (availableModels.find((m) => m.id === nextModelId && m.provider === ctx.model?.provider) ?? availableModels.find((m) => m.id === nextModelId));
-          if (modelToSet) {
-            const ok = await pi.setModel(modelToSet, { persist: false });
-            if (ok) {
-              ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
-              pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
-              return;
+    // --- Rate limit: skip model fallback, go straight to pause ---
+    // Rate-limiting is a provider issue, not a model issue.
+    // Switching models won't help if the provider is throttling you.
+    if (cls.kind === "rate-limit") {
+      await pauseTransientWithBackoff(cls, pi, ctx, errorDetail, true);
+      return;
+    }
+
+    // --- Server/connection/stream errors: try model fallback first ---
+    if (cls.kind === "network" || cls.kind === "server" || cls.kind === "connection" || cls.kind === "stream") {
+      // Try model fallback
+      const dash = getAutoDashboardData();
+      if (dash.currentUnit) {
+        const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
+        if (modelConfig && modelConfig.fallbacks.length > 0) {
+          const availableModels = ctx.modelRegistry.getAvailable();
+          const nextModelId = getNextFallbackModel(ctx.model?.id, modelConfig);
+          if (nextModelId) {
+            retryState.networkRetryCount = 0;
+            retryState.currentRetryModelId = undefined;
+            const modelToSet = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
+            if (modelToSet) {
+              const ok = await pi.setModel(modelToSet, { persist: false });
+              if (ok) {
+                ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
+                pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+                return;
+              }
             }
           }
         }
       }
-    }
 
-    const sessionModel = getAutoModeStartModel();
-    if (sessionModel) {
-      if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
-        const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
-        if (startModel) {
-          const ok = await pi.setModel(startModel, { persist: false });
-          if (ok) {
-            networkRetryCounters.clear();
-            ctx.ui.notify(`Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`, "warning");
-            pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
-            return;
+      // Try restoring session model
+      const sessionModel = getAutoModeStartModel();
+      if (sessionModel) {
+        if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
+          const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
+          if (startModel) {
+            const ok = await pi.setModel(startModel, { persist: false });
+            if (ok) {
+              retryState.networkRetryCount = 0;
+              retryState.currentRetryModelId = undefined;
+              ctx.ui.notify(`Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`, "warning");
+              pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+              return;
+            }
           }
         }
       }
     }
 
-    const classification = classifyProviderError(errorMsg);
-    const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
-    if (classification.isTransient) {
-      consecutiveTransientErrors += 1;
-    } else {
-      consecutiveTransientErrors = 0;
-    }
-    const baseRetryAfterMs = explicitRetryAfterMs ?? classification.suggestedDelayMs;
-    const retryAfterMs = classification.isTransient
-      ? baseRetryAfterMs * 2 ** Math.max(0, consecutiveTransientErrors - 1)
-      : baseRetryAfterMs;
-    const allowAutoResume = classification.isTransient && consecutiveTransientErrors <= MAX_TRANSIENT_AUTO_RESUMES;
-    if (classification.isTransient && !allowAutoResume) {
-      ctx.ui.notify(`Transient provider errors persisted after ${MAX_TRANSIENT_AUTO_RESUMES} auto-resume attempts. Pausing for manual review.`, "warning");
+    // --- Transient fallback: pause with auto-resume ---
+    if (isTransient(cls)) {
+      await pauseTransientWithBackoff(cls, pi, ctx, errorDetail, false);
+      return;
     }
+
+    // --- Permanent / unknown: pause indefinitely ---
     await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi), {
-      isRateLimit: classification.isRateLimit,
-      isTransient: allowAutoResume,
-      retryAfterMs,
-      resume: allowAutoResume
-        ? () => {
-          pi.sendMessage(
-            { customType: "gsd-auto-timeout-recovery", content: "Continue execution — provider error recovery delay elapsed.", display: false },
-            { triggerTurn: true },
-          );
-        }
-        : undefined,
+      isRateLimit: false,
+      isTransient: false,
+      retryAfterMs: 0,
     });
     return;
   }
 
+  // ── Success path ─────────────────────────────────────────────────────────
   try {
-    consecutiveTransientErrors = 0;
-    networkRetryCounters.clear();
+    resetRetryState(retryState);
     resolveAgentEnd(event);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -139,4 +183,3 @@ export async function handleAgentEnd(
     }
   }
 }
-

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
+import { setLogBasePath } from "../workflow-logger.js";
 
 /**
  * Resolve the correct DB path for the current working directory.
@@ -43,9 +44,14 @@ export async function ensureDbOpen(): Promise<boolean> {
     const dbPath = resolveProjectRootDbPath(basePath);
     const gsdDir = join(basePath, ".gsd");
 
+    // Derive the project root from the DB path (strip .gsd/gsd.db)
+    const projectRoot = join(dbPath, "..", "..");
+
     // Open existing DB file (may be at project root for worktrees)
     if (existsSync(dbPath)) {
-      return db.openDatabase(dbPath);
+      const opened = db.openDatabase(dbPath);
+      if (opened) setLogBasePath(projectRoot);
+      return opened;
     }
 
     // No DB file — create + migrate from Markdown if .gsd/ has content
@@ -56,6 +62,7 @@ export async function ensureDbOpen(): Promise<boolean> {
       if (hasDecisions || hasRequirements || hasMilestones) {
         const opened = db.openDatabase(dbPath);
         if (opened) {
+          setLogBasePath(projectRoot);
           try {
             const { migrateFromMarkdown } = await import("../md-importer.js");
             migrateFromMarkdown(basePath);
@@ -69,7 +76,9 @@ export async function ensureDbOpen(): Promise<boolean> {
       }
 
       // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
-      return db.openDatabase(dbPath);
+      const opened = db.openDatabase(dbPath);
+      if (opened) setLogBasePath(projectRoot);
+      return opened;
     }
 
     return false;

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -16,6 +16,8 @@ import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markTool
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
+import { startRtkStatusUpdates, stopRtkStatusUpdates } from "../rtk-status.js";
+import { rewriteCommandWithRtk } from "../../shared/rtk.js";
 
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
@@ -27,10 +29,19 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
 }
 
 export function registerHooks(pi: ExtensionAPI): void {
+  // Route all agent bash tool commands through RTK rewrite when opted in.
+  // This is a no-op when RTK is disabled or not installed.
+  pi.on("bash_transform", async (event) => {
+    const rewritten = rewriteCommandWithRtk(event.command);
+    if (rewritten === event.command) return undefined;
+    return { command: rewritten };
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     resetWriteGateState();
     resetToolCallLoopGuard();
     await syncServiceTierStatus(ctx);
+    startRtkStatusUpdates(ctx);
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -75,6 +86,11 @@ export function registerHooks(pi: ExtensionAPI): void {
     clearDiscussionFlowState();
     await syncServiceTierStatus(ctx);
     loadToolApiKeys();
+    startRtkStatusUpdates(ctx);
+  });
+
+  pi.on("session_fork", async (_event, ctx) => {
+    startRtkStatusUpdates(ctx);
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
@@ -123,6 +139,7 @@ export function registerHooks(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
+    stopRtkStatusUpdates(ctx);
     if (isParallelActive()) {
       try {
         await shutdownParallel(process.cwd());
@@ -228,7 +245,7 @@ export function registerHooks(pi: ExtensionAPI): void {
 
   pi.on("tool_execution_start", async (event) => {
     if (!isAutoActive()) return;
-    markToolStart(event.toolCallId);
+    markToolStart(event.toolCallId, event.toolName);
   });
 
   pi.on("tool_execution_end", async (event) => {

package/src/resources/extensions/gsd/claude-import.ts

@@ -103,16 +103,47 @@ function isMarketplacePath(pluginPath: string): boolean {
 
 /**
  * Detect which plugin roots are marketplaces and which are legacy flat paths.
+ *
+ * Claude Code stores marketplace sources under ~/.claude/plugins/marketplaces/.
+ * Each subdirectory (e.g. marketplaces/confluent/) is a marketplace repo that
+ * contains .claude-plugin/marketplace.json. The parent directory itself does not
+ * have a marketplace.json, so we scan one level deeper when the root isn't
+ * directly a marketplace.
  */
-function categorizePluginRoots(pluginRoots: string[]): { marketplaces: string[]; flat: string[] } {
+export function categorizePluginRoots(pluginRoots: string[]): { marketplaces: string[]; flat: string[] } {
   const marketplaces: string[] = [];
   const flat: string[] = [];
+  const seen = new Set<string>();
 
   for (const root of pluginRoots) {
     if (isMarketplacePath(root)) {
-      marketplaces.push(root);
+      if (!seen.has(root)) {
+        marketplaces.push(root);
+        seen.add(root);
+      }
     } else {
-      flat.push(root);
+      // The root itself isn't a marketplace — check if it's a container of
+      // marketplaces (e.g. ~/.claude/plugins/marketplaces/ contains subdirs
+      // like confluent/, claude-hud/, each with their own marketplace.json).
+      let foundChild = false;
+      try {
+        const entries = readdirSync(root, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          if (SKIP_DIRS.has(entry.name)) continue;
+          const childPath = join(root, entry.name);
+          if (isMarketplacePath(childPath) && !seen.has(childPath)) {
+            marketplaces.push(childPath);
+            seen.add(childPath);
+            foundChild = true;
+          }
+        }
+      } catch {
+        // Can't read directory — fall through to flat
+      }
+      if (!foundChild) {
+        flat.push(root);
+      }
     }
   }
 
@@ -170,18 +201,36 @@ export function discoverClaudePlugins(cwd: string): ClaudePluginCandidate[] {
 
   for (const root of pluginRoots) {
     walkDirs(root, (dir) => {
+      // Recognize both npm-style plugins (package.json) and Claude Code plugins
+      // (.claude-plugin/plugin.json). Claude marketplace-installed plugins use
+      // the latter format exclusively.
       const pkgPath = join(dir, "package.json");
-      if (!existsSync(pkgPath)) return;
+      const claudePluginPath = join(dir, ".claude-plugin", "plugin.json");
+      const hasPkg = existsSync(pkgPath);
+      const hasClaudePlugin = existsSync(claudePluginPath);
+      if (!hasPkg && !hasClaudePlugin) return;
+
       const resolvedDir = resolve(dir);
       if (seen.has(resolvedDir)) return;
       seen.add(resolvedDir);
+
       let packageName: string | undefined;
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
-        packageName = pkg.name;
-      } catch {
-        packageName = undefined;
+      if (hasPkg) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+          packageName = pkg.name;
+        } catch {
+          packageName = undefined;
+        }
+      } else if (hasClaudePlugin) {
+        try {
+          const manifest = JSON.parse(readFileSync(claudePluginPath, "utf8")) as { name?: string };
+          packageName = manifest.name;
+        } catch {
+          packageName = undefined;
+        }
       }
+
       results.push({
         type: "plugin",
         name: packageName || basename(dir),

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

@@ -7,6 +7,7 @@ import { enableDebug } from "../../debug-logger.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAuto, stopAuto, stopAutoRemote } from "../../auto.js";
 import { handleRate } from "../../commands-rate.js";
 import { guardRemoteSession, projectRoot } from "../context.js";
+import { findMilestoneIds } from "../../milestone-id-utils.js";
 
 /**
  * Parse --yolo flag and optional file path from the auto command string.
@@ -28,6 +29,39 @@ function parseYoloFlag(trimmed: string): { yoloSeedFile: string | null; rest: st
   return { yoloSeedFile: filePath, rest };
 }
 
+/**
+ * Extract a milestone ID (e.g. M016 or M001-a3b4c5) from the command string.
+ * Returns the matched ID and the remaining string with the ID removed.
+ * The milestone ID pattern matches the format used by findMilestoneIds: M\d+ with
+ * an optional -[a-z0-9]{6} suffix for unique milestone IDs.
+ */
+export function parseMilestoneTarget(input: string): { milestoneId: string | null; rest: string } {
+  const match = input.match(/\b(M\d+(?:-[a-z0-9]{6})?)\b/);
+  if (!match) return { milestoneId: null, rest: input };
+  const rest = input.replace(match[0], "").replace(/\s+/g, " ").trim();
+  return { milestoneId: match[1], rest };
+}
+
+/**
+ * Set GSD_MILESTONE_LOCK to target a specific milestone, then run `fn`.
+ * Clears the env var when `fn` resolves or rejects, so the lock does not
+ * leak into subsequent commands in the same process.
+ */
+async function withMilestoneLock(milestoneId: string, fn: () => Promise<void>): Promise<void> {
+  const previous = process.env.GSD_MILESTONE_LOCK;
+  process.env.GSD_MILESTONE_LOCK = milestoneId;
+  try {
+    await fn();
+  } finally {
+    // Restore previous value (undefined → delete, else restore).
+    if (previous === undefined) {
+      delete process.env.GSD_MILESTONE_LOCK;
+    } else {
+      process.env.GSD_MILESTONE_LOCK = previous;
+    }
+  }
+}
+
 export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
   if (trimmed === "next" || trimmed.startsWith("next ")) {
     if (trimmed.includes("--dry-run")) {
@@ -35,21 +69,48 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       await handleDryRun(ctx, projectRoot());
       return true;
     }
-    const verboseMode = trimmed.includes("--verbose");
-    const debugMode = trimmed.includes("--debug");
+    const { milestoneId, rest: afterMilestone } = parseMilestoneTarget(trimmed);
+    const verboseMode = afterMilestone.includes("--verbose");
+    const debugMode = afterMilestone.includes("--debug");
     if (debugMode) enableDebug(projectRoot());
     if (!(await guardRemoteSession(ctx, pi))) return true;
-    await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
+
+    // Validate the milestone target exists and is not already complete.
+    if (milestoneId) {
+      const allIds = findMilestoneIds(projectRoot());
+      if (!allIds.includes(milestoneId)) {
+        ctx.ui.notify(`Milestone ${milestoneId} does not exist. Available: ${allIds.join(", ") || "(none)"}`, "error");
+        return true;
+      }
+    }
+
+    if (milestoneId) {
+      await withMilestoneLock(milestoneId, () =>
+        startAuto(ctx, pi, projectRoot(), verboseMode, { step: true }),
+      );
+    } else {
+      await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
+    }
     return true;
   }
 
   if (trimmed === "auto" || trimmed.startsWith("auto ")) {
-    const { yoloSeedFile, rest } = parseYoloFlag(trimmed);
-    const verboseMode = rest.includes("--verbose");
-    const debugMode = rest.includes("--debug");
+    const { yoloSeedFile, rest: afterYolo } = parseYoloFlag(trimmed);
+    const { milestoneId, rest: afterMilestone } = parseMilestoneTarget(afterYolo);
+    const verboseMode = afterMilestone.includes("--verbose");
+    const debugMode = afterMilestone.includes("--debug");
     if (debugMode) enableDebug(projectRoot());
     if (!(await guardRemoteSession(ctx, pi))) return true;
 
+    // Validate the milestone target exists and is not already complete.
+    if (milestoneId) {
+      const allIds = findMilestoneIds(projectRoot());
+      if (!allIds.includes(milestoneId)) {
+        ctx.ui.notify(`Milestone ${milestoneId} does not exist. Available: ${allIds.join(", ") || "(none)"}`, "error");
+        return true;
+      }
+    }
+
     if (yoloSeedFile) {
       const resolved = resolve(projectRoot(), yoloSeedFile);
       if (!existsSync(resolved)) {
@@ -66,6 +127,12 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       // when the LLM says "Milestone X ready."
       const { showHeadlessMilestoneCreation } = await import("../../guided-flow.js");
       await showHeadlessMilestoneCreation(ctx, pi, projectRoot(), seedContent);
+    } else if (milestoneId) {
+      // Target a specific milestone — use GSD_MILESTONE_LOCK so state
+      // derivation only sees this milestone (#2521).
+      await withMilestoneLock(milestoneId, () =>
+        startAuto(ctx, pi, projectRoot(), verboseMode),
+      );
     } else {
       await startAuto(ctx, pi, projectRoot(), verboseMode);
     }

package/src/resources/extensions/gsd/commands-config.ts

@@ -22,6 +22,12 @@ export const TOOL_KEYS = [
   { id: "groq",     env: "GROQ_API_KEY",      label: "Groq Voice",        hint: "console.groq.com" },
 ] as const;
 
+function getStoredToolKey(auth: AuthStorage, providerId: string): string | undefined {
+  const creds = auth.getCredentialsForProvider(providerId);
+  const cred = creds.find((c) => c.type === "api_key" && c.key);
+  return cred?.type === "api_key" ? cred.key : undefined;
+}
+
 /**
  * Load tool API keys from auth.json into environment variables.
  * Called at session startup to ensure tools have access to their credentials.
@@ -33,9 +39,9 @@ export function loadToolApiKeys(): void {
 
     const auth = AuthStorage.create(authPath);
     for (const tool of TOOL_KEYS) {
-      const cred = auth.get(tool.id);
-      if (cred && cred.type === "api_key" && cred.key && !process.env[tool.env]) {
-        process.env[tool.env] = cred.key;
+      const key = getStoredToolKey(auth, tool.id);
+      if (key && !process.env[tool.env]) {
+        process.env[tool.env] = key;
       }
     }
   } catch {
@@ -55,14 +61,14 @@ export async function handleConfig(ctx: ExtensionCommandContext): Promise<void>
   // Show current status
   const statusLines = ["GSD Tool Configuration\n"];
   for (const tool of TOOL_KEYS) {
-    const hasKey = !!process.env[tool.env] || !!(auth.get(tool.id) as { key?: string })?.key;
+    const hasKey = !!process.env[tool.env] || !!getStoredToolKey(auth, tool.id);
     statusLines.push(`  ${hasKey ? "\u2713" : "\u2717"} ${tool.label}${hasKey ? "" : ` \u2014 get key at ${tool.hint}`}`);
   }
   ctx.ui.notify(statusLines.join("\n"), "info");
 
   // Ask which tools to configure
   const options = TOOL_KEYS.map(t => {
-    const hasKey = !!process.env[t.env] || !!(auth.get(t.id) as { key?: string })?.key;
+    const hasKey = !!process.env[t.env] || !!getStoredToolKey(auth, t.id);
     return `${t.label} ${hasKey ? "(configured \u2713)" : "(not set)"}`;
   });
   options.push("(done)");

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -771,7 +771,7 @@ export async function ensurePreferencesFile(
   scope: "global" | "project",
 ): Promise<void> {
   if (!existsSync(path)) {
-    const template = await loadFile(join(dirname(fileURLToPath(import.meta.url)), "templates", "preferences.md"));
+    const template = await loadFile(join(dirname(fileURLToPath(import.meta.url)), "templates", "PREFERENCES.md"));
     if (!template) {
       ctx.ui.notify("Could not load GSD preferences template.", "error");
       return;

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

@@ -76,12 +76,16 @@ export function readCrashLock(basePath: string): LockData | null {
 /**
  * Check whether the process that wrote the lock is still running.
  * Uses `process.kill(pid, 0)` which sends no signal but checks liveness.
- * Returns false if the PID matches our own (recycled PID from a prior run).
+ * Returns true if the PID matches our own — we are the lock holder (#2470).
  */
 export function isLockProcessAlive(lock: LockData): boolean {
   const pid = lock.pid;
   if (!Number.isInteger(pid) || pid <= 0) return false;
-  if (pid === process.pid) return false;
+  // Our own PID means WE hold this lock — we are alive. (#2470)
+  // Callers that need to distinguish "our lock" from "someone else's lock"
+  // (e.g. startAuto checking for a prior crashed session with a recycled PID)
+  // already guard with `crashLock.pid !== process.pid` before calling us.
+  if (pid === process.pid) return true;
   try {
     process.kill(pid, 0);
     return true;

package/src/resources/extensions/gsd/custom-execution-policy.ts

@@ -14,6 +14,7 @@
 import type { ExecutionPolicy } from "./execution-policy.js";
 import type { RecoveryAction, CloseoutResult } from "./engine-types.js";
 import { runCustomVerification } from "./custom-verification.js";
+import { parseUnitId } from "./unit-id.js";
 
 export class CustomExecutionPolicy implements ExecutionPolicy {
   private readonly runDir: string;
@@ -48,8 +49,8 @@ export class CustomExecutionPolicy implements ExecutionPolicy {
     unitId: string,
     _context: { basePath: string },
   ): Promise<"continue" | "retry" | "pause"> {
-    const parts = unitId.split("/");
-    const stepId = parts[parts.length - 1];
+    const { milestone, slice, task } = parseUnitId(unitId);
+    const stepId = task ?? slice ?? milestone;
     return runCustomVerification(this.runDir, stepId);
   }