gsd-pi 2.23.0 → 2.25.0

package/dist/resources/extensions/gsd/preferences.ts

@@ -75,6 +75,7 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "token_profile",
   "phases",
   "auto_visualize",
+  "parallel",
 ]);
 
 export interface GSDSkillRule {
@@ -171,6 +172,7 @@ export interface GSDPreferences {
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
   auto_visualize?: boolean;
+  parallel?: import("./types.js").ParallelConfig;
 }
 
 export interface LoadedGSDPreferences {
@@ -688,6 +690,7 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
           skip_research: true,
           skip_reassess: true,
           skip_slice_research: true,
+          skip_milestone_validation: true,
         },
       };
     case "balanced":
@@ -767,6 +770,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     phases: (base.phases || override.phases)
       ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
       : undefined,
+    parallel: (base.parallel || override.parallel)
+      ? { ...(base.parallel ?? {}), ...(override.parallel ?? {}) } as import("./types.js").ParallelConfig
+      : undefined,
   };
 }
 
@@ -909,8 +915,9 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (p.skip_research !== undefined) validatedPhases.skip_research = !!p.skip_research;
       if (p.skip_reassess !== undefined) validatedPhases.skip_reassess = !!p.skip_reassess;
       if (p.skip_slice_research !== undefined) validatedPhases.skip_slice_research = !!p.skip_slice_research;
+      if (p.skip_milestone_validation !== undefined) validatedPhases.skip_milestone_validation = !!p.skip_milestone_validation;
       // Warn on unknown phase keys
-      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research"]);
+      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation"]);
       for (const key of Object.keys(p)) {
         if (!knownPhaseKeys.has(key)) {
           warnings.push(`unknown phases key "${key}" — ignored`);
@@ -1152,6 +1159,51 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Parallel Config ────────────────────────────────────────────────────
+  if (preferences.parallel && typeof preferences.parallel === "object") {
+    const p = preferences.parallel as unknown as Record<string, unknown>;
+    const parallel: Record<string, unknown> = {};
+
+    if (p.enabled !== undefined) {
+      if (typeof p.enabled === "boolean") parallel.enabled = p.enabled;
+      else errors.push("parallel.enabled must be a boolean");
+    }
+    if (p.max_workers !== undefined) {
+      if (typeof p.max_workers === "number" && p.max_workers >= 1 && p.max_workers <= 4) {
+        parallel.max_workers = Math.floor(p.max_workers);
+      } else {
+        errors.push("parallel.max_workers must be a number between 1 and 4");
+      }
+    }
+    if (p.budget_ceiling !== undefined) {
+      if (typeof p.budget_ceiling === "number" && p.budget_ceiling > 0) {
+        parallel.budget_ceiling = p.budget_ceiling;
+      } else {
+        errors.push("parallel.budget_ceiling must be a positive number");
+      }
+    }
+    if (p.merge_strategy !== undefined) {
+      const validStrategies = new Set(["per-slice", "per-milestone"]);
+      if (typeof p.merge_strategy === "string" && validStrategies.has(p.merge_strategy)) {
+        parallel.merge_strategy = p.merge_strategy;
+      } else {
+        errors.push("parallel.merge_strategy must be one of: per-slice, per-milestone");
+      }
+    }
+    if (p.auto_merge !== undefined) {
+      const validModes = new Set(["auto", "confirm", "manual"]);
+      if (typeof p.auto_merge === "string" && validModes.has(p.auto_merge)) {
+        parallel.auto_merge = p.auto_merge;
+      } else {
+        errors.push("parallel.auto_merge must be one of: auto, confirm, manual");
+      }
+    }
+
+    if (Object.keys(parallel).length > 0) {
+      validated.parallel = parallel as unknown as import("./types.js").ParallelConfig;
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};
@@ -1369,3 +1421,15 @@ export function updatePreferencesModels(models: GSDModelConfigV2): void {
 
   writeFileSync(prefsPath, content, "utf-8");
 }
+
+// ─── Parallel Config Resolver ──────────────────────────────────────────────
+
+export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {
+  return {
+    enabled: prefs?.parallel?.enabled ?? false,
+    max_workers: Math.max(1, Math.min(4, prefs?.parallel?.max_workers ?? 2)),
+    budget_ceiling: prefs?.parallel?.budget_ceiling,
+    merge_strategy: prefs?.parallel?.merge_strategy ?? "per-milestone",
+    auto_merge: prefs?.parallel?.auto_merge ?? "confirm",
+  };
+}

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -28,7 +28,7 @@ Then:
 7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
-10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
+10. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 12. Update `.gsd/STATE.md`
 

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -0,0 +1,86 @@
+# Headless Milestone Creation
+
+You are creating a GSD milestone from a provided specification document. This is a **headless** (non-interactive) flow — do NOT ask the user any questions. Work entirely from the provided specification.
+
+## Provided Specification
+
+{{seedContext}}
+
+## Your Task
+
+### Step 1: Reflect
+
+Summarize your understanding of the specification concretely:
+- What is being built
+- Major capabilities/features
+- Scope estimate (how many milestones × slices)
+- Any ambiguities or gaps you notice
+
+### Step 2: Investigate
+
+Scout the codebase to understand what already exists:
+- `ls` the project root and key directories
+- Search for relevant existing code, patterns, dependencies
+- Check library docs if needed (`resolve_library` / `get_library_docs`)
+
+### Step 3: Make Decisions
+
+For any ambiguities or gaps in the specification:
+- Make your best-guess decision based on the spec's intent, codebase patterns, and domain conventions
+- Document each assumption clearly in the Context file
+
+### Step 4: Assess Scope
+
+Based on reflection + investigation:
+- Is this a single milestone or multiple milestones?
+- If multi-milestone: plan the full sequence with dependencies
+
+### Step 5: Write Artifacts
+
+**Milestone ID**: {{milestoneId}}
+
+Use these templates exactly:
+
+{{inlinedTemplates}}
+
+**For single milestone**, write in this order:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Write `.gsd/PROJECT.md` (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` (using Requirements template)
+4. Write `{{contextPath}}` (using Context template) — preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. Document assumptions under an "Assumptions" section.
+5. Write `{{roadmapPath}}` (using Roadmap template) — decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice.
+6. Seed `.gsd/DECISIONS.md` (using Decisions template)
+7. Update `.gsd/STATE.md`
+8. {{commitInstruction}}
+9. Say exactly: "Milestone {{milestoneId}} ready."
+
+**For multi-milestone**, write in this order:
+1. Create all milestone directories: `mkdir -p .gsd/milestones/{M###}/slices` for each
+2. Write `.gsd/PROJECT.md` — full vision across ALL milestones (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` — full capability contract (using Requirements template)
+4. Seed `.gsd/DECISIONS.md` (using Decisions template)
+5. Write PRIMARY `{{contextPath}}` — full context with all assumptions documented
+6. Write PRIMARY `{{roadmapPath}}` — detailed slices for the first milestone only
+7. For each remaining milestone, write full CONTEXT.md with `depends_on` frontmatter:
+   ```yaml
+   ---
+   depends_on: [M001, M002]
+   ---
+
+   # M003: Title
+   ```
+   Each context file should be rich enough that a future agent — with no memory of this conversation — can understand the intent, constraints, dependencies, what the milestone unlocks, and what "done" looks like.
+8. Update `.gsd/STATE.md`
+9. {{multiMilestoneCommitInstruction}}
+10. Say exactly: "Milestone {{milestoneId}} ready."
+
+## Critical Rules
+
+- **DO NOT ask the user any questions** — this is headless mode
+- **Preserve the specification's terminology** — don't paraphrase domain-specific language
+- **Document assumptions** — when you make a judgment call, note it in CONTEXT.md under "Assumptions"
+- **Investigate before writing** — always scout the codebase first
+- **Use depends_on frontmatter** for multi-milestone sequences (the state machine reads this field to determine execution order)
+- **Anti-reduction rule** — if the spec describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or reduce scope. Phase complex/risky work into later milestones — do not cut it.
+- **Naming convention** — directories use bare IDs (`M001/`, `S01/`), files use ID-SUFFIX format (`M001-CONTEXT.md`, `M001-ROADMAP.md`)
+- **End with "Milestone {{milestoneId}} ready."** — this triggers auto-start detection

package/dist/resources/extensions/gsd/prompts/discuss.md

@@ -201,9 +201,9 @@ When writing context.md, preserve the user's exact terminology, emphasis, and sp
 5. Write `{{roadmapPath}}` — use the **Roadmap** output template below. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
 6. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below. Append rows for any architectural or pattern decisions made during discussion.
 7. Update `.gsd/STATE.md`
-8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
+8. {{commitInstruction}}
 
-After writing the files and committing, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -271,8 +271,8 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 #### Phase 4: Finalize
 
 7. Update `.gsd/STATE.md`
-8. Commit: `docs: project plan — N milestones` (replace N with the actual milestone count)
+8. {{multiMilestoneCommitInstruction}}
 
-After writing the files and committing, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -63,7 +63,7 @@ Then:
 14. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 15. Write `{{taskSummaryPath}}`
 16. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
-17. Do not commit manually — the system auto-commits your changes after this unit completes.
+17. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
 18. Update `.gsd/STATE.md`
 
 All work stays in your working directory: `{{workingDirectory}}`.

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -104,5 +104,5 @@ Once the user confirms depth:
 1. Use the **Context** output template below
 2. `mkdir -p` the milestone directory if needed
 3. Write `{{milestoneId}}-CONTEXT.md` — preserve the user's exact terminology, emphasis, and framing. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
-4. Commit: `git add {{milestoneId}}-CONTEXT.md && git commit -m "docs({{milestoneId}}): milestone context from discuss"`
+4. {{commitInstruction}}
 5. Say exactly: `"{{milestoneId}} context written."` — nothing else.

package/dist/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -55,7 +55,7 @@ Once the user is ready to wrap up:
    - **Constraints** — anything the user flagged as a hard constraint
    - **Integration Points** — what this slice consumes and produces
    - **Open Questions** — anything still unresolved, with current thinking
-4. Commit: `git -C {{projectRoot}} add {{contextPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
+4. {{commitInstruction}}
 5. Say exactly: `"{{sliceId}} context written."` — nothing else.
 
 {{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -59,7 +59,7 @@ Then:
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
     - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding.
 9. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
-10. Commit: `docs({{sliceId}}): add slice plan`
+10. {{commitInstruction}}
 11. Update `.gsd/STATE.md`
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.

package/dist/resources/extensions/gsd/prompts/queue.md

@@ -96,7 +96,7 @@ Then, after all milestone directories and context files are written:
 4. If `.gsd/REQUIREMENTS.md` exists and the queued work introduces new in-scope capabilities or promotes Deferred items, update it.
 5. If discussion produced decisions relevant to existing work, append to `.gsd/DECISIONS.md`.
 6. Append to `.gsd/QUEUE.md`.
-7. Commit: `docs: queue <milestone list>`
+7. {{commitInstruction}}
 
 **Do NOT write roadmaps for queued milestones.**
 **Do NOT update `.gsd/STATE.md`.**

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -57,7 +57,7 @@ Write `{{assessmentPath}}` with a brief confirmation that roadmap coverage still
 1. Rewrite the remaining (unchecked) slices in `{{roadmapPath}}`. Keep completed slices exactly as they are (`[x]`). Update the boundary map for changed slices. Update the proof strategy if risks changed. Update requirement coverage if ownership or scope changed.
 2. Write `{{assessmentPath}}` explaining what changed and why — keep it brief and concrete.
 3. If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, update it.
-4. Commit: `docs({{milestoneId}}): reassess roadmap after {{completedSliceId}}`
+4. {{commitInstruction}}
 
 **You MUST write the file `{{assessmentPath}}` before finishing.**
 

package/dist/resources/extensions/gsd/prompts/research-slice.md

@@ -46,7 +46,7 @@ Research what this slice needs. Narrate key findings and surprises as you go —
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content
+5. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
 6. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -1,6 +1,6 @@
 You are executing GSD auto-mode.
 
-## UNIT: Validate Milestone {{milestoneId}} ("{{milestoneTitle}}") — Remediation Round {{remediationRound}}
+## UNIT: Validate Milestone {{milestoneId}} ("{{milestoneTitle}}")
 
 ## Working Directory
 
@@ -8,84 +8,63 @@ Your working directory is `{{workingDirectory}}`. All file reads, writes, and sh
 
 ## Your Role in the Pipeline
 
-All slices are done. Before the **complete-milestone agent** closes this milestone, you reconcile planned work against what was actually delivered. You audit success criteria against evidence, inventory deferred work across all slice summaries and UAT results, and classify gaps. If auto-remediable gaps exist on the first pass, you append remediation slices to the roadmap so the pipeline can execute them before completion. After remediation slices run, you re-validate. The milestone only proceeds to completion once validation passes.
+All slices are done. Before the milestone can be completed, you must validate that the planned work was delivered as specified. Compare the roadmap's success criteria and slice definitions against the actual slice summaries and UAT results. This is a reconciliation gate — catch gaps, regressions, or missing deliverables before the milestone is sealed.
 
-This is a gate, not a formality. But most milestones pass — bias toward "pass" unless you find concrete evidence of unmet criteria or meaningful gaps.
+This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues.
 
 All relevant context has been preloaded below — the roadmap, all slice summaries, UAT results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
 
 {{inlinedContext}}
 
-If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during validation, without relaxing required verification or artifact rules.
+## Validation Steps
 
-Then:
+1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion.
+2. For each **slice** in the roadmap, verify its demo/deliverable claim against its summary. Flag any slice whose summary does not substantiate its claimed output.
+3. Check **cross-slice integration points** — do boundary map entries (produces/consumes) align with what was actually built?
+4. Check **requirement coverage** — are all active requirements addressed by at least one slice?
+5. Determine a verdict:
+   - `pass` — all criteria met, all slices delivered, no gaps
+   - `needs-attention` — minor gaps that do not block completion (document them)
+   - `needs-remediation` — material gaps found; add remediation slices to the roadmap
 
-### Step 1: Audit Success Criteria
+## Output
 
-Enumerate each success criterion from the roadmap's `## Success Criteria` section. For each criterion, map it to concrete evidence from slice summaries, UAT results, or observable behavior.
+Write `{{validationPath}}` with this structure:
 
-Format each criterion as:
+```markdown
+---
+verdict: <pass|needs-attention|needs-remediation>
+remediation_round: {{remediationRound}}
+---
 
-- `Criterion text` — **MET** — evidence: {{specific slice summary, UAT result, test output, or observable behavior}}
-- `Criterion text` — **NOT MET** — gap: {{what's missing and why}}
+# Milestone Validation: {{milestoneId}}
 
-Every criterion must have a definitive verdict. Do not mark a criterion as MET without specific evidence.
+## Success Criteria Checklist
+- [x] Criterion 1 — evidence: ...
+- [ ] Criterion 2 — gap: ...
 
-### Step 2: Inventory Deferred Work
+## Slice Delivery Audit
+| Slice | Claimed | Delivered | Status |
+|-------|---------|-----------|--------|
+| S01   | ...     | ...       | pass   |
 
-Scan ALL slice summaries for:
-- `Known Limitations` sections
-- `Follow-ups` sections
-- `Deviations` sections
+## Cross-Slice Integration
+(any boundary mismatches)
 
-Scan ALL UAT results for:
-- `Not Proven By This UAT` sections
-- Any PARTIAL or FAIL verdicts
+## Requirement Coverage
+(any unaddressed requirements)
 
-Check:
-- `.gsd/REQUIREMENTS.md` for Active requirements not yet Validated
-- `.gsd/CAPTURES.md` for unresolved deferred captures
+## Verdict Rationale
+(why this verdict was chosen)
 
-Collect every item into a single inventory. Do not skip items because they seem minor — the classification step handles prioritization.
+## Remediation Plan
+(only if verdict is needs-remediation — list new slices to add to the roadmap)
+```
 
-### Step 3: Classify Each Gap
-
-For every unmet criterion and every deferred work item, classify it as one of:
-
-- **auto-remediable** — can be fixed by adding a new slice (missing feature, unfixed bug, untested path, incomplete integration)
-- **human-required** — needs Lex's input (design decision, external service dependency, manual verification, judgment call, ambiguous requirement)
-- **acceptable** — known limitation that's OK to ship (documented trade-off, explicitly scoped for a future milestone, minor rough edge with no user impact)
-
-Be conservative with **auto-remediable**. Only classify a gap as auto-remediable if you're confident a slice can resolve it without human judgment. When in doubt, classify as **human-required**.
-
-### Step 4: Act on Gaps
-
-**If this is remediation round 0 AND auto-remediable gaps exist:**
-
-1. Define remediation slices to address auto-remediable gaps. Follow the exact roadmap slice format:
-   `- [ ] **S0X: Title** \`risk:medium\` \`depends:[]\``
-   Include a brief description of what each slice must accomplish.
-2. Append these slices to `{{roadmapPath}}` after existing slices (do not modify completed slices).
-3. Update the boundary map in the roadmap if the new slices introduce new integration points.
-4. Set verdict to `needs-remediation`.
-
-**If this is remediation round 1 or higher:**
-
-Do NOT add more slices. At this point either:
-- All remaining gaps are acceptable — set verdict to `pass`
-- Remaining gaps need Lex's input — set verdict to `needs-attention`
-
-Never add remediation slices after round 0. If round 0 remediation didn't close the gaps, escalate.
-
-**If no auto-remediable gaps exist (any round):**
-
-- If all criteria are MET and deferred items are acceptable or human-required only — set verdict to `pass` (with human-required items noted)
-- If human-required items are blocking — set verdict to `needs-attention`
-
-### Step 5: Write Validation Report
-
-Write `{{validationPath}}` using the milestone-validation template. Fill all frontmatter fields and every section. The report must be a complete record of the validation — a future agent reading only this file should understand what was checked, what passed, and what remains.
+If verdict is `needs-remediation`:
+- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
+- These slices will be planned and executed before validation re-runs
 
 **You MUST write `{{validationPath}}` before finishing.**
 
-When done, say: "Milestone {{milestoneId}} validated."
+When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/dist/resources/extensions/gsd/provider-error-pause.ts

@@ -2,11 +2,38 @@ export type ProviderErrorPauseUI = {
   notify(message: string, level?: "info" | "warning" | "error" | "success"): void;
 };
 
+/**
+ * Pause auto-mode due to a provider error.
+ *
+ * For rate-limit errors with a known reset delay, schedules an automatic
+ * resume after the delay and shows a countdown notification. For all other
+ * errors, pauses indefinitely (user must manually resume).
+ */
 export async function pauseAutoForProviderError(
   ui: ProviderErrorPauseUI,
   errorDetail: string,
   pause: () => Promise<void>,
+  options?: {
+    isRateLimit?: boolean;
+    retryAfterMs?: number;
+    resume?: () => void;
+  },
 ): Promise<void> {
-  ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
-  await pause();
+  if (options?.isRateLimit && options.retryAfterMs && options.retryAfterMs > 0 && options.resume) {
+    const delaySec = Math.ceil(options.retryAfterMs / 1000);
+    ui.notify(
+      `Rate limited${errorDetail}. Auto-resuming in ${delaySec}s...`,
+      "warning",
+    );
+    await pause();
+
+    // Schedule auto-resume after the rate limit window
+    setTimeout(() => {
+      ui.notify("Rate limit window elapsed. Resuming auto-mode.", "info");
+      options.resume!();
+    }, options.retryAfterMs);
+  } else {
+    ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
+    await pause();
+  }
 }