gsd-pi 2.71.0-dev.06b86c6 → 2.71.0-dev.246c32d

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

@@ -1,79 +1,98 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { Key } from "@gsd/pi-tui";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.js";
 import { GSDNotificationOverlay } from "../notification-overlay.js";
 import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js";
+import { GSD_SHORTCUTS } from "../shortcut-defs.js";
 import { projectRoot } from "../commands/context.js";
 import { shortcutDesc } from "../../shared/mod.js";
 
 export function registerShortcuts(pi: ExtensionAPI): void {
-  pi.registerShortcut(Key.ctrlAlt("g"), {
-    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      if (!existsSync(join(basePath, ".gsd"))) {
-        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
+  const overlayOptions = {
+    width: "90%",
+    minWidth: 80,
+    maxHeight: "92%",
+    anchor: "center",
+  } as const;
+
+  const openDashboardOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    if (!existsSync(join(basePath, ".gsd"))) {
+      ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  const openNotificationsOverlay = async (ctx: ExtensionContext) => {
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions: {
+          width: "80%",
+          minWidth: 60,
+          maxHeight: "88%",
+          anchor: "center",
+          backdrop: true,
         },
-      );
-    },
+      },
+    );
+  };
+
+  const openParallelOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    const parallelDir = join(basePath, ".gsd", "parallel");
+    if (!existsSync(parallelDir)) {
+      ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true), basePath),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.dashboard.action, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("n"), {
-    description: shortcutDesc("Open notification history", "/gsd notifications"),
-    handler: async (ctx) => {
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "80%",
-            minWidth: 60,
-            maxHeight: "88%",
-            anchor: "center",
-            backdrop: true,
-          },
-        },
-      );
-    },
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.dashboard.action} (fallback)`, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("p"), {
-    description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      const parallelDir = join(basePath, ".gsd", "parallel");
-      if (!existsSync(parallelDir)) {
-        ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
-        },
-      );
-    },
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.notifications.action, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
   });
+
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.notifications.action} (fallback)`, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
+  });
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.parallel.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.parallel.action, GSD_SHORTCUTS.parallel.command),
+    handler: openParallelOverlay,
+  });
+
+  // No Ctrl+Shift+P fallback — conflicts with cycleModelBackward (shift+ctrl+p).
+  // Use Ctrl+Alt+P or /gsd parallel watch instead.
 }

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

@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { enableDebug } from "../../debug-logger.js";
-import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAuto, stopAuto, stopAutoRemote } from "../../auto.js";
+import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAutoDetached, stopAuto, stopAutoRemote } from "../../auto.js";
 import { handleRate } from "../../commands-rate.js";
 import { guardRemoteSession, projectRoot } from "../context.js";
 import { findMilestoneIds } from "../../milestone-id-utils.js";
@@ -42,26 +42,6 @@ export function parseMilestoneTarget(input: string): { milestoneId: string | nul
   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")) {
@@ -84,13 +64,10 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       }
     }
 
-    if (milestoneId) {
-      await withMilestoneLock(milestoneId, () =>
-        startAuto(ctx, pi, projectRoot(), verboseMode, { step: true }),
-      );
-    } else {
-      await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
-    }
+    startAutoDetached(ctx, pi, projectRoot(), verboseMode, {
+      step: true,
+      milestoneLock: milestoneId,
+    });
     return true;
   }
 
@@ -128,13 +105,11 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       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),
-      );
+      startAutoDetached(ctx, pi, projectRoot(), verboseMode, {
+        milestoneLock: milestoneId,
+      });
     } else {
-      await startAuto(ctx, pi, projectRoot(), verboseMode);
+      startAutoDetached(ctx, pi, projectRoot(), verboseMode);
     }
     return true;
   }
@@ -175,10 +150,9 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
 
   if (trimmed === "") {
     if (!(await guardRemoteSession(ctx, pi))) return true;
-    await startAuto(ctx, pi, projectRoot(), false, { step: true });
+    startAutoDetached(ctx, pi, projectRoot(), false, { step: true });
     return true;
   }
 
   return false;
 }
-

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

@@ -8,11 +8,45 @@ import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard
 import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
+import { setSessionModelOverride } from "../../session-model-override.js";
 import { projectRoot } from "../context.js";
-import { formatShortcut } from "../../files.js";
+import { formattedShortcutPair } from "../../shortcut-defs.js";
 
-export function showHelp(ctx: ExtensionCommandContext): void {
-  const lines = [
+export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
+  const summaryLines = [
+    "GSD — Get Shit Done\n",
+    "QUICK START",
+    "  /gsd start <tpl>   Start a workflow template",
+    "  /gsd               Run next unit (same as /gsd next)",
+    "  /gsd auto          Run all queued units continuously",
+    "  /gsd pause         Pause auto-mode",
+    "  /gsd stop          Stop auto-mode gracefully",
+    "",
+    "VISIBILITY",
+    `  /gsd status         Dashboard  (${formattedShortcutPair("dashboard")})`,
+    `  /gsd parallel watch Parallel monitor  (${formattedShortcutPair("parallel")})`,
+    `  /gsd notifications  Notification history  (${formattedShortcutPair("notifications")})`,
+    "  /gsd visualize      Interactive 10-tab TUI",
+    "  /gsd queue          Show queued/dispatched units",
+    "",
+    "COURSE CORRECTION",
+    "  /gsd steer <desc>   Apply user override to active work",
+    "  /gsd capture <text> Quick-capture a thought to CAPTURES.md",
+    "  /gsd triage         Classify and route pending captures",
+    "  /gsd undo           Revert last completed unit  [--force]",
+    "  /gsd rethink        Conversational project reorganization",
+    "",
+    "SETUP",
+    "  /gsd init           Project init wizard",
+    "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
+    "  /gsd model          Switch active session model",
+    "  /gsd prefs          Manage preferences",
+    "  /gsd doctor         Diagnose and repair .gsd/ state",
+    "",
+    "Use /gsd help full for the complete command reference.",
+  ];
+
+  const fullLines = [
     "GSD — Get Shit Done\n",
     "WORKFLOW",
     "  /gsd start <tpl>   Start a workflow template (bugfix, spike, feature, hotfix, etc.)",
@@ -26,12 +60,13 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
     "",
     "VISIBILITY",
-    `  /gsd status         Show progress dashboard  (${formatShortcut("Ctrl+Alt+G")})`,
+    `  /gsd status         Show progress dashboard  (${formattedShortcutPair("dashboard")})`,
+    `  /gsd parallel watch Open parallel worker monitor  (${formattedShortcutPair("parallel")})`,
     "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
-    `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formatShortcut("Ctrl+Alt+N")})`,
+    `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formattedShortcutPair("notifications")})`,
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",
@@ -71,7 +106,8 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
     "  /gsd update         Update GSD to the latest version via npm",
   ];
-  ctx.ui.notify(lines.join("\n"), "info");
+  const full = ["full", "--full", "all"].includes(args.trim().toLowerCase());
+  ctx.ui.notify((full ? fullLines : summaryLines).join("\n"), "info");
 }
 
 export async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
@@ -92,9 +128,9 @@ export async function handleStatus(ctx: ExtensionCommandContext): Promise<void>
     {
       overlay: true,
       overlayOptions: {
-        width: "70%",
-        minWidth: 60,
-        maxHeight: "90%",
+        width: "90%",
+        minWidth: 80,
+        maxHeight: "92%",
         anchor: "center",
       },
     },
@@ -301,6 +337,17 @@ async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi
     return;
   }
 
+  // /gsd model is an explicit per-session pin for GSD dispatches.
+  // This is captured at auto bootstrap so it survives internal session
+  // switches during /gsd auto and /gsd next runs.
+  const sessionId = ctx.sessionManager?.getSessionId?.();
+  if (sessionId) {
+    setSessionModelOverride(sessionId, {
+      provider: targetModel.provider,
+      id: targetModel.id,
+    });
+  }
+
   ctx.ui.notify(`Model: ${targetModel.provider}/${targetModel.id}`, "info");
 }
 
@@ -309,8 +356,8 @@ export async function handleCoreCommand(
   ctx: ExtensionCommandContext,
   pi?: ExtensionAPI,
 ): Promise<boolean> {
-  if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
-    showHelp(ctx);
+  if (trimmed === "help" || trimmed === "h" || trimmed === "?" || trimmed.startsWith("help ")) {
+    showHelp(ctx, trimmed.startsWith("help ") ? trimmed.slice(5).trim() : "");
     return true;
   }
   if (trimmed === "status") {

package/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts

@@ -13,6 +13,8 @@ import {
 } from "../../notification-store.js";
 import { GSDNotificationOverlay } from "../../notification-overlay.js";
 
+const MAX_INLINE_ENTRIES = 40;
+
 function severityIcon(severity: NotifySeverity): string {
   switch (severity) {
     case "error": return "✗";
@@ -54,8 +56,9 @@ export async function handleNotificationsCommand(
   if (args === "tail" || args.startsWith("tail ")) {
     const countStr = args.replace(/^tail\s*/, "").trim();
     const count = countStr ? parseInt(countStr, 10) : 20;
-    const n = isNaN(count) || count < 1 ? 20 : Math.min(count, 100);
-    const entries = readNotifications().slice(0, n);
+    const all = readNotifications();
+    const n = isNaN(count) || count < 1 ? 20 : Math.min(count, MAX_INLINE_ENTRIES);
+    const entries = all.slice(0, n);
 
     if (entries.length === 0) {
       ctx.ui.notify("No notifications.", "info");
@@ -65,7 +68,10 @@ export async function handleNotificationsCommand(
     const lines = entries.map((e) =>
       `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
     );
-    ctx.ui.notify(`Last ${entries.length} notification(s):\n${lines.join("\n")}`, "info");
+    const suffix = all.length > entries.length
+      ? `\n... and ${all.length - entries.length} more (open /gsd notifications to browse all)`
+      : "";
+    ctx.ui.notify(`Last ${entries.length} notification(s):\n${lines.join("\n")}${suffix}`, "info");
     return true;
   }
 
@@ -86,7 +92,9 @@ export async function handleNotificationsCommand(
     const lines = entries.slice(0, 20).map((e) =>
       `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
     );
-    const suffix = entries.length > 20 ? `\n... and ${entries.length - 20} more` : "";
+    const suffix = entries.length > 20
+      ? `\n... and ${entries.length - 20} more (open /gsd notifications to browse all)`
+      : "";
     ctx.ui.notify(`${severity} notifications (${entries.length}):\n${lines.join("\n")}${suffix}`, "info");
     return true;
   }
@@ -96,8 +104,8 @@ export async function handleNotificationsCommand(
     // Try overlay first (TUI mode)
     if (ctx.hasUI) {
       try {
-        await ctx.ui.custom<void>(
-          (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()),
+        const result = await ctx.ui.custom<boolean>(
+          (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
           {
             overlay: true,
             overlayOptions: {
@@ -109,7 +117,9 @@ export async function handleNotificationsCommand(
             },
           },
         );
-        return true;
+        if (result !== undefined) {
+          return true;
+        }
       } catch {
         // Fall through to text output if overlay fails
       }

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

@@ -18,7 +18,7 @@ import { createRun, listRuns } from "../../run-manager.js";
 import {
   setActiveEngineId,
   setActiveRunDir,
-  startAuto,
+  startAutoDetached,
   pauseAuto,
   isAutoActive,
   getActiveEngineId,
@@ -77,7 +77,7 @@ async function handleCustomWorkflow(
       setActiveEngineId("custom");
       setActiveRunDir(runDir);
       ctx.ui.notify(`Created workflow run: ${defName}\nRun dir: ${runDir}`, "info");
-      await startAuto(ctx, pi, base, false);
+      startAutoDetached(ctx, pi, base, false);
     } catch (err) {
       // Clean up engine state so a failed workflow run doesn't pollute the next /gsd auto
       setActiveEngineId(null);
@@ -157,13 +157,8 @@ async function handleCustomWorkflow(
       ctx.ui.notify("No custom workflow to resume. Use /gsd auto for dev workflow.", "warning");
       return true;
     }
-    try {
-      await startAuto(ctx, pi, projectRoot(), false);
-      ctx.ui.notify("Custom workflow resumed.", "info");
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      ctx.ui.notify(`Failed to resume workflow: ${msg}`, "error");
-    }
+    startAutoDetached(ctx, pi, projectRoot(), false);
+    ctx.ui.notify("Custom workflow resumed.", "info");
     return true;
   }
 
@@ -278,4 +273,3 @@ export function getNextMilestoneId(basePath: string): string {
   const uniqueIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
   return nextMilestoneId(milestoneIds, uniqueIds);
 }
-

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

@@ -3,7 +3,8 @@
  *
  * Full-screen overlay showing auto-mode progress: milestone/slice/task
  * breakdown, current unit, completed units, timing, and activity log.
- * Toggled with Ctrl+Alt+G (⌃⌥G on macOS) or opened from /gsd status.
+ * Toggled with Ctrl+Alt+G (⌃⌥G on macOS), Ctrl+Shift+G fallback,
+ * or opened from /gsd status.
  */
 
 import type { Theme } from "@gsd/pi-coding-agent";
@@ -26,6 +27,7 @@ import { formatDuration, padRight, joinColumns, centerLine, fitColumns, STATUS_G
 import { estimateTimeRemaining } from "./auto-dashboard.js";
 import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 import { runEnvironmentChecks, type EnvironmentCheckResult } from "./doctor-environment.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 
 function unitLabel(type: string): string {
   switch (type) {
@@ -203,7 +205,12 @@ export class GSDDashboardOverlay {
   }
 
   handleInput(data: string): void {
-    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c")) || matchesKey(data, Key.ctrlAlt("g"))) {
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl("c")) ||
+      matchesKey(data, Key.ctrlAlt("g")) ||
+      matchesKey(data, Key.ctrlShift("g"))
+    ) {
       this.dispose();
       this.onClose();
       return;
@@ -587,7 +594,7 @@ export class GSDDashboardOverlay {
 
     lines.push(blank());
     lines.push(hr());
-    lines.push(centered(th.fg("dim", "↑↓ scroll · g/G top/end · esc close")));
+    lines.push(centered(th.fg("dim", `↑↓ scroll · g/G top/end · Esc/${formattedShortcutPair("dashboard")} close`)));
 
     return lines;
   }

package/src/resources/extensions/gsd/doctor-providers.ts

@@ -185,11 +185,35 @@ const PROVIDER_ROUTES: Record<string, string[]> = {
   google: ["google-gemini-cli"],
 };
 
+/**
+ * Providers that use external CLI authentication (not API keys).
+ * These are always considered "ok" — the host CLI handles auth.
+ */
+const CLI_AUTH_PROVIDERS = new Set([
+  "claude-code",
+  "openai-codex",
+  "google-gemini-cli",
+  "google-antigravity",
+]);
+
 function checkLlmProviders(): ProviderCheckResult[] {
   const required = collectConfiguredModelProviders();
   const results: ProviderCheckResult[] = [];
 
   for (const providerId of required) {
+    // CLI-authenticated providers don't need API keys — skip key check
+    if (CLI_AUTH_PROVIDERS.has(providerId)) {
+      const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+      results.push({
+        name: providerId,
+        label: info?.label ?? providerId,
+        category: "llm",
+        status: "ok",
+        message: `${info?.label ?? providerId} — CLI auth (no key needed)`,
+        required: true,
+      });
+      continue;
+    }
     const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
     const label = providerId === "anthropic-vertex"
       ? "Anthropic Vertex"

package/src/resources/extensions/gsd/error-classifier.ts

@@ -44,6 +44,9 @@ export function resetRetryState(state: RetryState): void {
 
 const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i;
 const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
+// OpenRouter affordability-style quota errors should be treated as transient
+// so core retry logic can lower maxTokens and continue in-session.
+const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
 const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
@@ -67,7 +70,7 @@ const RESET_DELAY_RE = /reset in (\d+)s/i;
  */
 export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorClass {
   const isPermanent = PERMANENT_RE.test(errorMsg);
-  const isRateLimit = RATE_LIMIT_RE.test(errorMsg);
+  const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
 
   // 1. Permanent — but rate limit takes precedence
   if (isPermanent && !isRateLimit) {

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

@@ -650,19 +650,33 @@ function getDbCompletionCounts(): DbCompletionCounts | null {
  * Exported for testability.
  */
 export function detectStuckLoops(units: UnitMetrics[], anomalies: ForensicAnomaly[]): void {
-  // First, collect unique startedAt values per type/id key
-  const dispatchMap = new Map<string, Set<number>>();
+  // First, collect unique startedAt values per type/id key, bucketed by
+  // autoSessionKey when available so cross-session recovery does not look
+  // like a within-session stuck loop.
+  const dispatchMap = new Map<string, Map<string, Set<number>>>();
   for (const u of units) {
     const key = `${u.type}/${u.id}`;
-    let starts = dispatchMap.get(key);
+    let sessionBuckets = dispatchMap.get(key);
+    if (!sessionBuckets) {
+      sessionBuckets = new Map();
+      dispatchMap.set(key, sessionBuckets);
+    }
+
+    const sessionKey = u.autoSessionKey ?? "__legacy__";
+    let starts = sessionBuckets.get(sessionKey);
     if (!starts) {
       starts = new Set();
-      dispatchMap.set(key, starts);
+      sessionBuckets.set(sessionKey, starts);
     }
     starts.add(u.startedAt);
   }
-  for (const [key, starts] of dispatchMap) {
-    const count = starts.size;
+
+  for (const [key, sessionBuckets] of dispatchMap) {
+    const hasSessionAwareData = Array.from(sessionBuckets.keys()).some((sessionKey) => sessionKey !== "__legacy__");
+    const count = hasSessionAwareData
+      ? Math.max(...Array.from(sessionBuckets.values(), (starts) => starts.size))
+      : (sessionBuckets.get("__legacy__")?.size ?? 0);
+
     if (count > 1) {
       const [unitType, ...idParts] = key.split("/");
       anomalies.push({
@@ -671,7 +685,9 @@ export function detectStuckLoops(units: UnitMetrics[], anomalies: ForensicAnomal
         unitType,
         unitId: idParts.join("/"),
         summary: `Unit ${key} was dispatched ${count} times`,
-        details: `Repeated dispatch suggests the unit completed but its artifacts weren't verified, or the state machine kept returning it.`,
+        details: hasSessionAwareData
+          ? `Repeated dispatch within the same auto session suggests the unit completed but its artifacts were not verified, or the state machine kept returning it. Cross-session recovery runs are ignored.`
+          : `Repeated dispatch suggests the unit completed but its artifacts weren't verified, or the state machine kept returning it.`,
       });
     }
   }