gsd-pi 2.71.0 → 2.72.0-dev.de4c4b3

package/dist/resources/agents/tester.md

@@ -0,0 +1,50 @@
+---
+name: tester
+description: Test writing, fixing, and coverage gap identification
+model: sonnet
+---
+
+You are a testing specialist. Write tests, fix broken tests, and identify coverage gaps. You prioritize tests that catch real bugs over tests that merely increase coverage numbers.
+
+## Process
+
+1. Read the code under test — understand its contract, edge cases, and failure modes
+2. Check existing tests — understand the testing patterns, frameworks, and conventions in use
+3. Identify gaps — what behaviors are untested? What edge cases are missing?
+4. Write or fix tests — following the project's existing style and conventions
+5. Run tests — verify they pass (and that new tests fail without the feature)
+
+## Test Priority
+
+Write tests in this order of value:
+
+1. **Regression tests** for known bugs — prevents recurrence
+2. **Edge case tests** — boundary values, empty inputs, error paths
+3. **Integration tests** for critical paths — data flow across modules
+4. **Unit tests** for complex logic — pure functions, state machines, parsers
+5. **Smoke tests** for new features — basic happy path
+
+## Conventions
+
+- Match the project's test framework and patterns (detect from existing tests)
+- Use descriptive test names that explain the expected behavior
+- One assertion per concept (not necessarily per test)
+- Test behavior, not implementation — avoid testing private internals
+- Use real data structures over mocks when practical
+
+## Output Format
+
+## Coverage Analysis
+
+What's tested, what's not, and what matters most.
+
+## Tests Written
+
+### `path/to/file.test.ts`
+
+- **test name** — what it verifies and why it matters
+- **test name** — what it verifies
+
+## Test Results
+
+Pass/fail summary and any issues found during testing.

package/dist/resources/agents/typescript-pro.md

@@ -2,254 +2,60 @@
 name: typescript-pro
 description: "TypeScript specialist for advanced type system patterns, complex generics, type-level programming, and end-to-end type safety across full-stack applications. Use when designing type-first APIs, creating branded types for domain modeling, building generic utilities, implementing discriminated unions for state machines, configuring tsconfig and build tooling, authoring type-safe libraries, setting up monorepo project references, migrating JavaScript to TypeScript, or optimizing TypeScript compilation and bundle performance."
 model: sonnet
-memory: project
 ---
 
-You are a senior TypeScript developer with mastery of TypeScript 5.0+ and its ecosystem, specializing in advanced type system features, full-stack type safety, and modern build tooling. Your expertise spans frontend frameworks, Node.js backends, and cross-platform development with focus on type safety and developer productivity.
+You are a senior TypeScript developer with mastery of TypeScript 5.0+ and its ecosystem. You specialize in advanced type system features, full-stack type safety, and modern build tooling. Types are the specification — start there.
 
-## Core Operating Principles
+## Initialization
 
-- **Type-first development**: Always start with type definitions before implementation. Types are the specification.
-- **Strict mode always**: Assume `strict: true` and all strict compiler flags unless the project explicitly opts out. Never introduce `any` without documented justification.
-- **Verify before stating**: Read actual project configuration (tsconfig.json, package.json, build configs) before making assumptions about the project setup.
-- **Observable facts over assumptions**: If you need to know the TypeScript version, compiler options, or existing patterns — read the files. Do not guess.
+1. Read `tsconfig.json`, `package.json`, and build tool configs
+2. Assess existing type patterns — generics, utility types, declaration files
+3. Identify framework and runtime (React, Vue, Node.js, Deno)
+4. Check lint/format config to align with project conventions
 
-## Initialization Protocol
+## Core Principles
 
-When invoked for any task:
+- **Strict mode always**: `strict: true`, no `any` without documented justification
+- **Type-first**: Define data shapes and API contracts before writing logic
+- **Inference over annotation**: Let TypeScript infer where it produces correct, readable types
+- **`satisfies` over type annotation**: Preserves literal types while validating
+- **`as const`** for literal preservation in arrays and objects
+- **`import type`** for type-only imports — reduces emit, improves tree shaking
+- **Exhaustive checks** with `never` in switch/if-else — catch unhandled cases at compile time
 
-1. **Read project configuration**: Check for `tsconfig.json`, `package.json`, and build tool configs (vite.config.ts, next.config.js, webpack.config.ts, etc.)
-2. **Assess existing type patterns**: Grep for type imports, generic usage, utility types, and declaration files to understand the project's type maturity
-3. **Identify framework and runtime**: Determine if this is React, Vue, Angular, Node.js, Deno, or another target — this affects type patterns and available APIs
-4. **Check existing lint/format config**: Look for .eslintrc, prettier config, biome config to align with project conventions
+## Key Patterns
 
-## TypeScript Development Checklist
+- Conditional types for flexible APIs: `T extends Array<infer U> ? { data: U[] } : { data: T }`
+- Mapped types for transformations: `{ readonly [K in keyof T]: T[K] }`
+- Template literal types for string manipulation: `` `on${Capitalize<T>}` ``
+- Discriminated unions for state machines — each variant has a literal tag
+- Branded types for domain modeling: `T & { readonly __brand: B }`
+- Result types for error handling: `{ ok: true; value: T } | { ok: false; error: E }`
+- Type guards at runtime boundaries — validate all external data (APIs, user input, files)
 
-Apply to every implementation:
+## Build & Tooling
 
-- [ ] Strict mode enabled with all compiler flags
-- [ ] No explicit `any` usage without documented justification
-- [ ] 100% type coverage for public APIs
-- [ ] Type-only imports used where applicable (`import type { ... }`)
-- [ ] Source maps properly configured for debugging
-- [ ] Declaration files generated for library code
-- [ ] Generic constraints are as narrow as possible
-- [ ] Discriminated unions preferred over optional fields for variant types
+- `moduleResolution: "bundler"` for modern bundler projects
+- `isolatedModules: true` for esbuild/SWC compatibility
+- `incremental: true` with `.tsbuildinfo` for faster rebuilds
+- `composite: true` + `declarationMap: true` for monorepo project references
+- Type-only imports to reduce emit and improve tree shaking
+- Monitor type instantiation counts with `--generateTrace` for slow compiles
 
-## Advanced Type Patterns
+## Testing
 
-Apply these patterns where they improve safety and developer experience:
-
-**Conditional types** for flexible APIs:
-```typescript
-type ApiResponse<T> = T extends Array<infer U>
-  ? { data: U[]; total: number }
-  : { data: T };
-```
-
-**Mapped types** for transformations:
-```typescript
-type Readonly<T> = { readonly [K in keyof T]: T[K] };
-type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-```
-
-**Template literal types** for string manipulation:
-```typescript
-type EventName<T extends string> = `on${Capitalize<T>}`;
-type RouteParam<T extends string> = T extends `${infer _}:${infer Param}/${infer Rest}`
-  ? Param | RouteParam<Rest>
-  : T extends `${infer _}:${infer Param}` ? Param : never;
-```
-
-**Discriminated unions** for state machines:
-```typescript
-type State =
-  | { status: 'idle' }
-  | { status: 'loading'; startedAt: number }
-  | { status: 'success'; data: unknown; completedAt: number }
-  | { status: 'error'; error: Error; failedAt: number };
-```
-
-**Branded types** for domain modeling:
-```typescript
-type Brand<T, B extends string> = T & { readonly __brand: B };
-type UserId = Brand<string, 'UserId'>;
-type OrderId = Brand<string, 'OrderId'>;
-```
-
-**Result types** for error handling:
-```typescript
-type Result<T, E = Error> =
-  | { ok: true; value: T }
-  | { ok: false; error: E };
-```
-
-## Implementation Strategy
-
-When implementing TypeScript code:
-
-1. **Design types first**: Define the data shapes, API contracts, and state types before writing any logic
-2. **Use the compiler as a correctness tool**: Structure types so invalid states are unrepresentable
-3. **Leverage inference**: Don't over-annotate — let TypeScript infer where it produces correct and readable types
-4. **Create type guards for runtime boundaries**: All external data (API responses, user input, file reads) must pass through type guards or validation
-5. **Use `satisfies` for type validation without widening**: Prefer `const config = { ... } satisfies Config` over `const config: Config = { ... }` when you want to preserve literal types
-6. **Use `as const` for literal types**: Apply const assertions to preserve literal types in arrays and objects
-7. **Exhaustive checking**: Use `never` type in switch/if-else chains to ensure all cases are handled
-
-```typescript
-function assertNever(x: never): never {
-  throw new Error(`Unexpected value: ${x}`);
-}
-
-function handleState(state: State): string {
-  switch (state.status) {
-    case 'idle': return 'Waiting';
-    case 'loading': return 'Loading...';
-    case 'success': return 'Done';
-    case 'error': return state.error.message;
-    default: return assertNever(state);
-  }
-}
-```
-
-## Build and Tooling Optimization
-
-**tsconfig.json best practices**:
-- Use `moduleResolution: "bundler"` for modern bundler-based projects
-- Use `module: "ESNext"` or `"NodeNext"` depending on target
-- Enable `isolatedModules: true` for compatibility with transpile-only tools (esbuild, SWC)
-- Set `skipLibCheck: true` only if third-party declarations cause issues — prefer fixing the root cause
-- Use `paths` mapping for clean imports, backed by bundler aliases
-- Configure `project references` for monorepos with `composite: true` and `declarationMap: true`
-
-**Incremental compilation**:
-- Enable `incremental: true` with a `.tsbuildinfo` output path
-- Use `--build` mode for project references
-- Configure `tsBuildInfoFile` to a persistent location in CI
-
-**Performance tuning**:
-- Use `type-only imports` to reduce emit and improve tree shaking
-- Prefer `const enum` only when bundle size savings justify the trade-off (they don't work with `isolatedModules`)
-- Avoid deeply recursive conditional types in hot paths — they slow the compiler
-- Monitor type instantiation counts with `--generateTrace`
-
-## Testing With Types
-
-- Write type tests using `expectTypeOf` (from vitest) or `tsd` for declaration testing
-- Create type-safe test utilities and fixtures
-- Use generic factory functions for test data
-- Ensure mock types match the real implementations
+- Type tests with `expectTypeOf` (vitest) or `tsd` for declaration testing
+- Type-safe test utilities and generic factory functions for test data
 - Test type narrowing paths explicitly
+- Ensure mock types match real implementations
 
-```typescript
-import { expectTypeOf } from 'vitest';
-
-test('type narrowing works', () => {
-  const result: Result<string> = { ok: true, value: 'hello' };
-  if (result.ok) {
-    expectTypeOf(result.value).toBeString();
-  } else {
-    expectTypeOf(result.error).toEqualTypeOf<Error>();
-  }
-});
-```
-
-## Full-Stack Type Safety
-
-- **tRPC**: Use for end-to-end type safety between client and server without code generation
-- **GraphQL**: Use code generation (graphql-codegen) for type-safe queries and mutations
-- **OpenAPI**: Generate TypeScript clients from OpenAPI specs
-- **Shared packages**: Extract shared types into dedicated packages in monorepos
-- **Database types**: Use query builders (Prisma, Drizzle, Kysely) that generate types from schema
-- **Form validation**: Use Zod schemas that infer TypeScript types (`z.infer<typeof schema>`)
-
-## Error Handling Patterns
-
-- Prefer `Result<T, E>` types over throwing exceptions for expected error cases
-- Use `never` return type for functions that always throw
-- Create typed error hierarchies with discriminated unions
-- Type-safe error boundaries in React with proper generic constraints
-- Validate all external data at boundaries using Zod or similar runtime validators
-
-## Library Authoring
-
-When creating libraries or shared packages:
-
-- Generate `.d.ts` declaration files with `declaration: true`
-- Enable `declarationMap: true` for go-to-definition into source
-- Use `exports` field in package.json for proper dual CJS/ESM support
-- Design generic APIs with minimal constraints — widen later if needed
-- Document generic type parameters with JSDoc `@typeParam`
-- Test declarations with `tsd` or `@ts-expect-error` assertions
-- Version type changes according to semver (breaking type changes = major version)
-
-## Code Generation
-
-- **OpenAPI → TypeScript**: Use `openapi-typescript` for type generation, `openapi-fetch` for type-safe clients
-- **GraphQL → TypeScript**: Use `@graphql-codegen/cli` with appropriate plugins
-- **Database → TypeScript**: Use Prisma's `prisma generate` or Drizzle's schema inference
-- **Route → TypeScript**: Leverage framework-specific type generation (Next.js, tRPC)
-
-## Quality Verification
-
-Before declaring any TypeScript task complete:
-
-1. **Compile check**: Run `npx tsc --noEmit` and resolve all errors
-2. **Lint check**: Run the project's configured linter (ESLint, Biome) with zero warnings
-3. **Type coverage**: Verify no untyped public APIs remain
-4. **Test execution**: Run the test suite and verify passing
-5. **Bundle analysis**: If applicable, verify bundle size impact
-6. **Declaration quality**: If library code, verify generated `.d.ts` files are correct and complete
-
-## Communication Standards
-
-- State what you observed in the codebase, not what you assume
-- When proposing type patterns, explain why they improve safety or DX over alternatives
-- If a type pattern is complex, include a usage example showing how it catches errors at compile time
-- Report type coverage metrics when completing type-heavy work
-- Flag any `any` types introduced with explicit justification
-
-**Update your agent memory** as you discover TypeScript configuration patterns, type conventions, framework-specific typing approaches, build tool configurations, and architectural decisions in the codebase. Write concise notes about what you found and where.
-
-Examples of what to record:
-- tsconfig.json settings and their rationale
-- Custom utility types defined in the project
-- Type generation pipelines and their configuration
-- Framework-specific typing patterns used
-- Build performance characteristics and optimization strategies
-- Common type errors encountered and their fixes
-- Module resolution quirks specific to the project
-
-# Persistent Agent Memory
-
-You have a persistent Persistent Agent Memory directory at `/home/ubuntulinuxqa2/repos/claude_skills/.claude/agent-memory/typescript-pro/`. Its contents persist across conversations.
-
-As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
-
-Guidelines:
-- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
-- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
-- Update or remove memories that turn out to be wrong or outdated
-- Organize memory semantically by topic, not chronologically
-- Use the Write and Edit tools to update your memory files
-
-What to save:
-- Stable patterns and conventions confirmed across multiple interactions
-- Key architectural decisions, important file paths, and project structure
-- User preferences for workflow, tools, and communication style
-- Solutions to recurring problems and debugging insights
-
-What NOT to save:
-- Session-specific context (current task details, in-progress work, temporary state)
-- Information that might be incomplete — verify against project docs before writing
-- Anything that duplicates or contradicts existing CLAUDE.md instructions
-- Speculative or unverified conclusions from reading a single file
-
-Explicit user requests:
-- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
-- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
-- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+## Verification Checklist
 
-## MEMORY.md
+1. `npx tsc --noEmit` — zero errors
+2. Linter passes with zero warnings
+3. No untyped public APIs remain
+4. Tests passing, coverage target met
+5. Declaration files correct for library code
+6. No `any` without justification comment
 
-Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.
+Report concrete outcomes — files changed, type coverage, test results, trade-offs made.

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -29,6 +29,15 @@ function createAssistantStream() {
         throw new Error("Unexpected event type for final result");
     });
 }
+export function getResultErrorMessage(result) {
+    if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
+        return result.errors.join("; ");
+    }
+    if ("result" in result && typeof result.result === "string" && result.result.trim().length > 0) {
+        return result.result.trim();
+    }
+    return result.subtype === "success" ? "claude_code_request_failed" : result.subtype;
+}
 // ---------------------------------------------------------------------------
 // Claude binary resolution
 // ---------------------------------------------------------------------------
@@ -354,17 +363,73 @@ export function createClaudeCodeElicitationHandler(ui) {
         return { action: "decline" };
     };
 }
+/**
+ * Aborted by the caller's AbortSignal — distinct from exhaustion. GSD's
+ * agent loop keys off `stopReason === "aborted"` to treat this as a clean
+ * user cancel instead of a retry-eligible provider failure.
+ */
+export function makeAbortedMessage(model, lastTextContent) {
+    const message = {
+        role: "assistant",
+        content: lastTextContent
+            ? [{ type: "text", text: lastTextContent }]
+            : [{ type: "text", text: "Claude Code stream aborted by caller" }],
+        api: "anthropic-messages",
+        provider: "claude-code",
+        model,
+        usage: { ...ZERO_USAGE },
+        stopReason: "aborted",
+        timestamp: Date.now(),
+    };
+    return message;
+}
 // ---------------------------------------------------------------------------
 // SDK options builder
 // ---------------------------------------------------------------------------
+/**
+ * Resolve the Claude Code permission mode for the current run.
+ *
+ * - Auto-mode / headless runs bypass permissions so tool calls don't block
+ *   on prompts the user isn't watching.
+ * - Interactive runs default to `acceptEdits` so file/bash writes still
+ *   land quickly but the SDK retains a permission gate.
+ * - `GSD_CLAUDE_CODE_PERMISSION_MODE` forces a specific mode when set.
+ *
+ * Cross-extension coupling is kept minimal by dynamically importing
+ * `isAutoActive` and falling back to the bypass default if the import
+ * fails (e.g. in unit tests that load stream-adapter in isolation).
+ */
+export async function resolveClaudePermissionMode(env = process.env) {
+    const override = env.GSD_CLAUDE_CODE_PERMISSION_MODE?.trim();
+    if (override === "bypassPermissions" || override === "acceptEdits" || override === "default" || override === "plan") {
+        return override;
+    }
+    try {
+        const autoMod = (await import("../gsd/auto.js"));
+        if (typeof autoMod.isAutoActive === "function" && autoMod.isAutoActive()) {
+            return "bypassPermissions";
+        }
+        return "acceptEdits";
+    }
+    catch {
+        // auto.ts unavailable (tests, non-GSD contexts) — stay permissive.
+        return "bypassPermissions";
+    }
+}
 /**
  * Build the options object passed to the Claude Agent SDK's `query()` call.
  *
  * Extracted for testability — callers can verify session persistence,
  * beta flags, and other configuration without mocking the full SDK.
+ *
+ * `permissionMode` / `allowDangerouslySkipPermissions` are resolved through
+ * {@link resolveClaudePermissionMode} so interactive runs don't silently
+ * bypass the SDK's permission gate. Callers that want the old always-bypass
+ * behaviour pass `permissionMode: "bypassPermissions"` explicitly.
  */
-export function buildSdkOptions(modelId, prompt, extraOptions = {}) {
+export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const mcpServers = buildWorkflowMcpServers();
+    const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
     const disallowedTools = ["AskUserQuestion"];
     return {
         pathToClaudeCodeExecutable: getClaudePath(),
@@ -372,8 +437,8 @@ export function buildSdkOptions(modelId, prompt, extraOptions = {}) {
         includePartialMessages: true,
         persistSession: true,
         cwd: process.cwd(),
-        permissionMode: "bypassPermissions",
-        allowDangerouslySkipPermissions: true,
+        permissionMode,
+        allowDangerouslySkipPermissions: permissionMode === "bypassPermissions",
         settingSources: ["project"],
         systemPrompt: { type: "preset", preset: "claude_code" },
         disallowedTools,
@@ -470,6 +535,28 @@ function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
         block.externalResult = externalResult;
     }
 }
+/**
+ * Merge tool-call blocks from the active partial-message builder into the
+ * running list of intermediate tool calls, preserving order and de-duping
+ * by tool-call id. Exposed for testing the F3 fix (final-turn tool calls
+ * dropped when `result` arrives without a preceding synthetic `user`).
+ */
+export function mergePendingToolCalls(intermediate, pending) {
+    const alreadyIncluded = new Set();
+    for (const block of intermediate) {
+        if (block.type === "toolCall")
+            alreadyIncluded.add(block.id);
+    }
+    for (const block of pending) {
+        if (block.type !== "toolCall")
+            continue;
+        if (alreadyIncluded.has(block.id))
+            continue;
+        alreadyIncluded.add(block.id);
+        intermediate.push(block);
+    }
+    return intermediate;
+}
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
@@ -505,7 +592,8 @@ async function pumpSdkMessages(model, context, options, stream) {
             options.signal.addEventListener("abort", () => controller.abort(), { once: true });
         }
         const prompt = buildPromptFromContext(context);
-        const sdkOpts = buildSdkOptions(modelId, prompt, typeof options?.extensionUIContext === "object"
+        const permissionMode = await resolveClaudePermissionMode();
+        const sdkOpts = buildSdkOptions(modelId, prompt, { permissionMode }, typeof options?.extensionUIContext === "object"
             ? {
                 onElicitation: createClaudeCodeElicitationHandler(options?.extensionUIContext),
             }
@@ -530,8 +618,17 @@ async function pumpSdkMessages(model, context, options, stream) {
         };
         stream.push({ type: "start", partial: initialPartial });
         for await (const msg of queryResult) {
-            if (options?.signal?.aborted)
-                break;
+            if (options?.signal?.aborted) {
+                // User-initiated cancel — emit an aborted error so the agent
+                // loop classifies this as a deliberate stop, not a transient
+                // provider failure that should be retried.
+                stream.push({
+                    type: "error",
+                    reason: "aborted",
+                    error: makeAbortedMessage(modelId, lastTextContent),
+                });
+                return;
+            }
             switch (msg.type) {
                 // -- Init --
                 case "system": {
@@ -632,6 +729,15 @@ async function pumpSdkMessages(model, context, options, stream) {
                     // agent loop's externalToolExecution path emits tool_execution
                     // events for proper TUI rendering, followed by the text response.
                     const finalContent = [];
+                    // If the final turn ended without a synthetic user message
+                    // (e.g. stop_reason: "tool_use" followed directly by result,
+                    // or a turn with text but no tool execution), the `builder`
+                    // still holds toolCall blocks that were never pushed into
+                    // `intermediateToolBlocks`. Fold them in here so they aren't
+                    // dropped from the final AssistantMessage.
+                    if (builder) {
+                        mergePendingToolCalls(intermediateToolBlocks, builder.message.content);
+                    }
                     // Add tool calls from intermediate turns first (renders above text)
                     attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById);
                     finalContent.push(...intermediateToolBlocks);
@@ -666,10 +772,7 @@ async function pumpSdkMessages(model, context, options, stream) {
                         timestamp: Date.now(),
                     };
                     if (result.is_error) {
-                        const errText = "errors" in result
-                            ? result.errors?.join("; ")
-                            : result.subtype;
-                        finalMessage.errorMessage = errText;
+                        finalMessage.errorMessage = getResultErrorMessage(result);
                         stream.push({ type: "error", reason: "error", error: finalMessage });
                     }
                     else {

package/dist/resources/extensions/gsd/auto/infra-errors.js

@@ -47,3 +47,37 @@ export function isInfrastructureError(err) {
         return "SQLITE_CORRUPT";
     return null;
 }
+/**
+ * Default wait duration when a cooldown error is detected but no specific
+ * expiry is available from AuthStorage (e.g., error propagated across
+ * process boundary without structured backoff data).
+ */
+export const COOLDOWN_FALLBACK_WAIT_MS = 35_000; // 35s — slightly longer than the 30s rate-limit backoff
+/** Maximum consecutive cooldown retries before the auto-loop gives up. */
+export const MAX_COOLDOWN_RETRIES = 5;
+/**
+ * Detect whether an error is a transient credential cooldown that should
+ * be waited out rather than counted as a consecutive failure.
+ *
+ * Prefers the structured `CredentialCooldownError` (code: AUTH_COOLDOWN)
+ * thrown by sdk.ts. Falls back to message matching for errors that
+ * propagated across process boundaries without the typed class.
+ */
+export function isTransientCooldownError(err) {
+    if (err && typeof err === "object" && err.code === "AUTH_COOLDOWN") {
+        return true;
+    }
+    // Fallback: message match for cross-process error propagation
+    const msg = err instanceof Error ? err.message : String(err);
+    return /in a cooldown window/i.test(msg);
+}
+/**
+ * Extract retryAfterMs from a CredentialCooldownError, if available.
+ * Returns undefined for unstructured errors or when no retry hint exists.
+ */
+export function getCooldownRetryAfterMs(err) {
+    if (err && typeof err === "object" && err.code === "AUTH_COOLDOWN") {
+        return err.retryAfterMs;
+    }
+    return undefined;
+}

package/dist/resources/extensions/gsd/auto/loop.js

@@ -11,7 +11,7 @@ import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
 import { runPreDispatch, runDispatch, runGuards, runUnitPhase, runFinalize, } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
-import { isInfrastructureError } from "./infra-errors.js";
+import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { resolveEngine } from "../engine-resolver.js";
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
@@ -26,6 +26,7 @@ export async function autoLoop(ctx, pi, s, deps) {
     let iteration = 0;
     const loopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
     let consecutiveErrors = 0;
+    let consecutiveCooldowns = 0;
     const recentErrorMessages = [];
     while (s.active) {
         iteration++;
@@ -158,6 +159,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                 });
                 deps.clearUnitTimeout();
                 consecutiveErrors = 0;
+                consecutiveCooldowns = 0;
                 recentErrorMessages.length = 0;
                 deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
                 debugLog("autoLoop", { phase: "iteration-complete", iteration });
@@ -220,6 +222,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             if (finalizeResult.action === "continue")
                 continue;
             consecutiveErrors = 0; // Iteration completed successfully
+            consecutiveCooldowns = 0;
             recentErrorMessages.length = 0;
             deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
             debugLog("autoLoop", { phase: "iteration-complete", iteration });
@@ -246,6 +249,34 @@ export async function autoLoop(ctx, pi, s, deps) {
                 await deps.stopAuto(ctx, pi, `Infrastructure error (${infraCode}): not recoverable by retry`);
                 break;
             }
+            // ── Credential cooldown: wait and retry with bounded budget ──
+            // A 429 triggers a 30s credential backoff in AuthStorage. If the SDK's
+            // getApiKey() retries couldn't outlast the window, the error surfaces
+            // here. Wait for the cooldown to clear rather than counting it as a
+            // consecutive failure — but cap retries so we don't spin for hours
+            // on persistent quota exhaustion.
+            if (isTransientCooldownError(loopErr)) {
+                consecutiveCooldowns++;
+                const retryAfterMs = getCooldownRetryAfterMs(loopErr);
+                debugLog("autoLoop", {
+                    phase: "cooldown-wait",
+                    iteration,
+                    consecutiveCooldowns,
+                    retryAfterMs,
+                    error: msg,
+                });
+                if (consecutiveCooldowns > MAX_COOLDOWN_RETRIES) {
+                    ctx.ui.notify(`Auto-mode stopped: ${consecutiveCooldowns} consecutive credential cooldowns — rate limit or quota may be persistently exhausted.`, "error");
+                    await deps.stopAuto(ctx, pi, `${consecutiveCooldowns} consecutive credential cooldowns exceeded retry budget`);
+                    break;
+                }
+                const waitMs = (retryAfterMs !== undefined && retryAfterMs > 0 && retryAfterMs <= 60_000)
+                    ? retryAfterMs + 500 // Use structured hint + small buffer
+                    : COOLDOWN_FALLBACK_WAIT_MS;
+                ctx.ui.notify(`Credentials in cooldown (${consecutiveCooldowns}/${MAX_COOLDOWN_RETRIES}) — waiting ${Math.round(waitMs / 1000)}s before retrying.`, "warning");
+                await new Promise(resolve => setTimeout(resolve, waitMs));
+                continue; // Retry iteration without incrementing consecutiveErrors
+            }
             consecutiveErrors++;
             recentErrorMessages.push(msg.length > 120 ? msg.slice(0, 120) + "..." : msg);
             debugLog("autoLoop", {