gsd-pi 2.34.0-dev.7d38042 → 2.34.0-dev.e6d9bed

package/packages/pi-tui/src/keys.ts

@@ -325,131 +325,74 @@ const FUNCTIONAL_CODEPOINTS = {
 	end: -15,
 } as const;
 
-const LEGACY_KEY_SEQUENCES = {
-	up: ["\x1b[A", "\x1bOA"],
-	down: ["\x1b[B", "\x1bOB"],
-	right: ["\x1b[C", "\x1bOC"],
-	left: ["\x1b[D", "\x1bOD"],
-	home: ["\x1b[H", "\x1bOH", "\x1b[1~", "\x1b[7~"],
-	end: ["\x1b[F", "\x1bOF", "\x1b[4~", "\x1b[8~"],
-	insert: ["\x1b[2~"],
-	delete: ["\x1b[3~"],
-	pageUp: ["\x1b[5~", "\x1b[[5~"],
-	pageDown: ["\x1b[6~", "\x1b[[6~"],
-	clear: ["\x1b[E", "\x1bOE"],
-	f1: ["\x1bOP", "\x1b[11~", "\x1b[[A"],
-	f2: ["\x1bOQ", "\x1b[12~", "\x1b[[B"],
-	f3: ["\x1bOR", "\x1b[13~", "\x1b[[C"],
-	f4: ["\x1bOS", "\x1b[14~", "\x1b[[D"],
-	f5: ["\x1b[15~", "\x1b[[E"],
-	f6: ["\x1b[17~"],
-	f7: ["\x1b[18~"],
-	f8: ["\x1b[19~"],
-	f9: ["\x1b[20~"],
-	f10: ["\x1b[21~"],
-	f11: ["\x1b[23~"],
-	f12: ["\x1b[24~"],
-} as const;
-
-const LEGACY_SHIFT_SEQUENCES = {
-	up: ["\x1b[a"],
-	down: ["\x1b[b"],
-	right: ["\x1b[c"],
-	left: ["\x1b[d"],
-	clear: ["\x1b[e"],
-	insert: ["\x1b[2$"],
-	delete: ["\x1b[3$"],
-	pageUp: ["\x1b[5$"],
-	pageDown: ["\x1b[6$"],
-	home: ["\x1b[7$"],
-	end: ["\x1b[8$"],
-} as const;
-
-const LEGACY_CTRL_SEQUENCES = {
-	up: ["\x1bOa"],
-	down: ["\x1bOb"],
-	right: ["\x1bOc"],
-	left: ["\x1bOd"],
-	clear: ["\x1bOe"],
-	insert: ["\x1b[2^"],
-	delete: ["\x1b[3^"],
-	pageUp: ["\x1b[5^"],
-	pageDown: ["\x1b[6^"],
-	home: ["\x1b[7^"],
-	end: ["\x1b[8^"],
-} as const;
-
-const LEGACY_SEQUENCE_KEY_IDS: Record<string, KeyId> = {
-	"\x1bOA": "up",
-	"\x1bOB": "down",
-	"\x1bOC": "right",
-	"\x1bOD": "left",
-	"\x1bOH": "home",
-	"\x1bOF": "end",
-	"\x1b[E": "clear",
-	"\x1bOE": "clear",
-	"\x1bOe": "ctrl+clear",
-	"\x1b[e": "shift+clear",
-	"\x1b[2~": "insert",
-	"\x1b[2$": "shift+insert",
-	"\x1b[2^": "ctrl+insert",
-	"\x1b[3$": "shift+delete",
-	"\x1b[3^": "ctrl+delete",
-	"\x1b[[5~": "pageUp",
-	"\x1b[[6~": "pageDown",
-	"\x1b[a": "shift+up",
-	"\x1b[b": "shift+down",
-	"\x1b[c": "shift+right",
-	"\x1b[d": "shift+left",
-	"\x1bOa": "ctrl+up",
-	"\x1bOb": "ctrl+down",
-	"\x1bOc": "ctrl+right",
-	"\x1bOd": "ctrl+left",
-	"\x1b[5$": "shift+pageUp",
-	"\x1b[6$": "shift+pageDown",
-	"\x1b[7$": "shift+home",
-	"\x1b[8$": "shift+end",
-	"\x1b[5^": "ctrl+pageUp",
-	"\x1b[6^": "ctrl+pageDown",
-	"\x1b[7^": "ctrl+home",
-	"\x1b[8^": "ctrl+end",
-	"\x1bOP": "f1",
-	"\x1bOQ": "f2",
-	"\x1bOR": "f3",
-	"\x1bOS": "f4",
-	"\x1b[11~": "f1",
-	"\x1b[12~": "f2",
-	"\x1b[13~": "f3",
-	"\x1b[14~": "f4",
-	"\x1b[[A": "f1",
-	"\x1b[[B": "f2",
-	"\x1b[[C": "f3",
-	"\x1b[[D": "f4",
-	"\x1b[[E": "f5",
-	"\x1b[15~": "f5",
-	"\x1b[17~": "f6",
-	"\x1b[18~": "f7",
-	"\x1b[19~": "f8",
-	"\x1b[20~": "f9",
-	"\x1b[21~": "f10",
-	"\x1b[23~": "f11",
-	"\x1b[24~": "f12",
-	"\x1bb": "alt+left",
-	"\x1bf": "alt+right",
-	"\x1bp": "alt+up",
-	"\x1bn": "alt+down",
+/**
+ * Consolidated legacy terminal key sequences.
+ * Each key maps to its sequences for unmodified, shift-modified, and ctrl-modified variants.
+ * This single structure replaces three separate maps (LEGACY_KEY_SEQUENCES,
+ * LEGACY_SHIFT_SEQUENCES, LEGACY_CTRL_SEQUENCES) that shared the same key sets.
+ */
+const LEGACY_SEQUENCES: Record<string, { plain?: readonly string[]; shift?: readonly string[]; ctrl?: readonly string[] }> = {
+	up:       { plain: ["\x1b[A", "\x1bOA"],                            shift: ["\x1b[a"],  ctrl: ["\x1bOa"]  },
+	down:     { plain: ["\x1b[B", "\x1bOB"],                            shift: ["\x1b[b"],  ctrl: ["\x1bOb"]  },
+	right:    { plain: ["\x1b[C", "\x1bOC"],                            shift: ["\x1b[c"],  ctrl: ["\x1bOc"]  },
+	left:     { plain: ["\x1b[D", "\x1bOD"],                            shift: ["\x1b[d"],  ctrl: ["\x1bOd"]  },
+	home:     { plain: ["\x1b[H", "\x1bOH", "\x1b[1~", "\x1b[7~"],   shift: ["\x1b[7$"], ctrl: ["\x1b[7^"] },
+	end:      { plain: ["\x1b[F", "\x1bOF", "\x1b[4~", "\x1b[8~"],   shift: ["\x1b[8$"], ctrl: ["\x1b[8^"] },
+	insert:   { plain: ["\x1b[2~"],                                      shift: ["\x1b[2$"], ctrl: ["\x1b[2^"] },
+	delete:   { plain: ["\x1b[3~"],                                      shift: ["\x1b[3$"], ctrl: ["\x1b[3^"] },
+	pageUp:   { plain: ["\x1b[5~", "\x1b[[5~"],                        shift: ["\x1b[5$"], ctrl: ["\x1b[5^"] },
+	pageDown: { plain: ["\x1b[6~", "\x1b[[6~"],                        shift: ["\x1b[6$"], ctrl: ["\x1b[6^"] },
+	clear:    { plain: ["\x1b[E", "\x1bOE"],                            shift: ["\x1b[e"],  ctrl: ["\x1bOe"]  },
+	f1:       { plain: ["\x1bOP", "\x1b[11~", "\x1b[[A"] },
+	f2:       { plain: ["\x1bOQ", "\x1b[12~", "\x1b[[B"] },
+	f3:       { plain: ["\x1bOR", "\x1b[13~", "\x1b[[C"] },
+	f4:       { plain: ["\x1bOS", "\x1b[14~", "\x1b[[D"] },
+	f5:       { plain: ["\x1b[15~", "\x1b[[E"] },
+	f6:       { plain: ["\x1b[17~"] },
+	f7:       { plain: ["\x1b[18~"] },
+	f8:       { plain: ["\x1b[19~"] },
+	f9:       { plain: ["\x1b[20~"] },
+	f10:      { plain: ["\x1b[21~"] },
+	f11:      { plain: ["\x1b[23~"] },
+	f12:      { plain: ["\x1b[24~"] },
 } as const;
 
-type LegacyModifierKey = keyof typeof LEGACY_SHIFT_SEQUENCES;
+/**
+ * Reverse lookup from escape sequence to key identifier, auto-generated from LEGACY_SEQUENCES.
+ * Additional non-standard sequences (alt+arrow aliases) are appended after generation.
+ */
+const LEGACY_SEQUENCE_KEY_IDS: Record<string, KeyId> = (() => {
+	const map: Record<string, KeyId> = {};
+	for (const [key, entry] of Object.entries(LEGACY_SEQUENCES)) {
+		const keyId = key as KeyId;
+		if (entry.plain) {
+			for (const seq of entry.plain) map[seq] = keyId;
+		}
+		if (entry.shift) {
+			for (const seq of entry.shift) map[seq] = `shift+${keyId}` as KeyId;
+		}
+		if (entry.ctrl) {
+			for (const seq of entry.ctrl) map[seq] = `ctrl+${keyId}` as KeyId;
+		}
+	}
+	// Non-standard alt+arrow aliases not derivable from the table
+	map["\x1bb"] = "alt+left";
+	map["\x1bf"] = "alt+right";
+	map["\x1bp"] = "alt+up";
+	map["\x1bn"] = "alt+down";
+	return map;
+})();
 
 const matchesLegacySequence = (data: string, sequences: readonly string[]): boolean => sequences.includes(data);
 
-const matchesLegacyModifierSequence = (data: string, key: LegacyModifierKey, modifier: number): boolean => {
-	if (modifier === MODIFIERS.shift) {
-		return matchesLegacySequence(data, LEGACY_SHIFT_SEQUENCES[key]);
+const matchesLegacyModifierSequence = (data: string, key: string, modifier: number): boolean => {
+	const entry = LEGACY_SEQUENCES[key];
+	if (!entry) return false;
+	if (modifier === MODIFIERS.shift && entry.shift) {
+		return matchesLegacySequence(data, entry.shift);
 	}
-	if (modifier === MODIFIERS.ctrl) {
-		return matchesLegacySequence(data, LEGACY_CTRL_SEQUENCES[key]);
+	if (modifier === MODIFIERS.ctrl && entry.ctrl) {
+		return matchesLegacySequence(data, entry.ctrl);
 	}
 	return false;
 };
@@ -481,33 +424,29 @@ interface ParsedModifyOtherKeysSequence {
 let _lastEventType: KeyEventType = "press";
 
 /**
- * Check if the last parsed key event was a key release.
- * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Check if input data contains a Kitty event type marker.
+ * Event type markers appear as ":<eventType>" followed by a sequence terminator (u, ~, A-D, H, F).
+ * Ignores bracketed paste content which may contain similar patterns.
  */
-export function isKeyRelease(data: string): boolean {
-	// Don't treat bracketed paste content as key release, even if it contains
-	// patterns like ":3F" (e.g., bluetooth MAC addresses like "90:62:3F:A5").
-	// Terminal.ts re-wraps paste content with bracketed paste markers before
-	// passing to TUI, so pasted data will always contain \x1b[200~.
+function hasKittyEventType(data: string, eventType: number): boolean {
 	if (data.includes("\x1b[200~")) {
 		return false;
 	}
+	const marker = `:${eventType}`;
+	return (
+		data.includes(`${marker}u`) ||
+		data.includes(`${marker}~`) ||
+		data.includes(`${marker}A`) ||
+		data.includes(`${marker}B`) ||
+		data.includes(`${marker}C`) ||
+		data.includes(`${marker}D`) ||
+		data.includes(`${marker}H`) ||
+		data.includes(`${marker}F`)
+	);
+}
 
-	// Quick check: release events with flag 2 contain ":3"
-	// Format: \x1b[<codepoint>;<modifier>:3u
-	if (
-		data.includes(":3u") ||
-		data.includes(":3~") ||
-		data.includes(":3A") ||
-		data.includes(":3B") ||
-		data.includes(":3C") ||
-		data.includes(":3D") ||
-		data.includes(":3H") ||
-		data.includes(":3F")
-	) {
-		return true;
-	}
-	return false;
+export function isKeyRelease(data: string): boolean {
+	return hasKittyEventType(data, 3);
 }
 
 /**
@@ -515,25 +454,7 @@ export function isKeyRelease(data: string): boolean {
  * Only meaningful when Kitty keyboard protocol with flag 2 is active.
  */
 export function isKeyRepeat(data: string): boolean {
-	// Don't treat bracketed paste content as key repeat, even if it contains
-	// patterns like ":2F". See isKeyRelease() for details.
-	if (data.includes("\x1b[200~")) {
-		return false;
-	}
-
-	if (
-		data.includes(":2u") ||
-		data.includes(":2~") ||
-		data.includes(":2A") ||
-		data.includes(":2B") ||
-		data.includes(":2C") ||
-		data.includes(":2D") ||
-		data.includes(":2H") ||
-		data.includes(":2F")
-	) {
-		return true;
-	}
-	return false;
+	return hasKittyEventType(data, 2);
 }
 
 function parseEventType(eventTypeStr: string | undefined): KeyEventType {
@@ -847,7 +768,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "insert":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.insert) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.insert.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.insert, 0)
 				);
 			}
@@ -859,7 +780,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "delete":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.delete) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.delete.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, 0)
 				);
 			}
@@ -870,14 +791,14 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 
 		case "clear":
 			if (modifier === 0) {
-				return matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.clear);
+				return matchesLegacySequence(data, LEGACY_SEQUENCES.clear.plain!);
 			}
 			return matchesLegacyModifierSequence(data, "clear", modifier);
 
 		case "home":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.home) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.home.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.home, 0)
 				);
 			}
@@ -889,7 +810,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "end":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.end) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.end.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.end, 0)
 				);
 			}
@@ -901,7 +822,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "pageup":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.pageUp) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.pageUp.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.pageUp, 0)
 				);
 			}
@@ -913,7 +834,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "pagedown":
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.pageDown) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.pageDown.plain!) ||
 					matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.pageDown, 0)
 				);
 			}
@@ -928,7 +849,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			}
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.up) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.up.plain!) ||
 					matchesKittySequence(data, ARROW_CODEPOINTS.up, 0)
 				);
 			}
@@ -943,7 +864,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			}
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.down) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.down.plain!) ||
 					matchesKittySequence(data, ARROW_CODEPOINTS.down, 0)
 				);
 			}
@@ -970,7 +891,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			}
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.left) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.left.plain!) ||
 					matchesKittySequence(data, ARROW_CODEPOINTS.left, 0)
 				);
 			}
@@ -997,7 +918,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			}
 			if (modifier === 0) {
 				return (
-					matchesLegacySequence(data, LEGACY_KEY_SEQUENCES.right) ||
+					matchesLegacySequence(data, LEGACY_SEQUENCES.right.plain!) ||
 					matchesKittySequence(data, ARROW_CODEPOINTS.right, 0)
 				);
 			}
@@ -1021,8 +942,8 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			if (modifier !== 0) {
 				return false;
 			}
-			const functionKey = key as keyof typeof LEGACY_KEY_SEQUENCES;
-			return matchesLegacySequence(data, LEGACY_KEY_SEQUENCES[functionKey]);
+			const functionKey = key as keyof typeof LEGACY_SEQUENCES;
+			return matchesLegacySequence(data, LEGACY_SEQUENCES[functionKey]!.plain!);
 		}
 	}
 

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

@@ -738,10 +738,14 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
   const orderedKeys = [
     "version", "mode", "always_use_skills", "prefer_skills", "avoid_skills",
     "skill_rules", "custom_instructions", "models", "skill_discovery",
-    "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
+    "skill_staleness_days", "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
     "notifications", "remote_questions", "git",
     "post_unit_hooks", "pre_dispatch_hooks",
+    "dynamic_routing", "token_profile", "phases", "parallel",
+    "auto_visualize", "auto_report",
+    "verification_commands", "verification_auto_fix", "verification_max_retries",
+    "search_provider", "compression_strategy", "context_selection",
   ];
 
   const seen = new Set<string>();

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -134,6 +134,10 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
+  - `auto_pr`: boolean — automatically create a GitHub pull request after a milestone branch is merged. Requires `gh` CLI to be installed. Default: `false`.
+  - `pr_target_branch`: string — branch to target when `auto_pr` is enabled. Defaults to `main_branch` when omitted.
+  - **Deprecated:** `commit_docs` — no longer valid; `.gsd/` is always gitignored. Remove this setting.
+  - **Deprecated:** `merge_to_main` — no longer valid; milestone-level merge is always used. Remove this setting.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
@@ -181,6 +185,12 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `auto_report`: boolean — generate an HTML report snapshot after each milestone completion. Default: `true`.
 
+- `search_provider`: `"brave"`, `"tavily"`, `"ollama"`, `"native"`, or `"auto"` — selects the search backend for research phases. `"native"` forces Anthropic's built-in web search only; provider values force that backend and disable native search; `"auto"` uses the default heuristic. Default: `"auto"`.
+
+- `compression_strategy`: `"truncate"` or `"compress"` — controls how context that exceeds the budget is reduced. `"truncate"` (default) drops sections from the end. `"compress"` applies heuristic compression before truncating, preserving more content at the cost of some fidelity. Default: `"truncate"`.
+
+- `context_selection`: `"full"` or `"smart"` — controls how files are inlined into context. `"full"` inlines entire files; `"smart"` uses semantic chunking to include only the most relevant sections. Default is derived from `token_profile`.
+
 - `parallel`: configures parallel orchestration for running multiple slices concurrently. Keys:
   - `enabled`: boolean — enable parallel execution. Default: `false`.
   - `max_workers`: number — maximum concurrent workers (1-4). Default: `2`.

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

@@ -1,15 +1,15 @@
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join, sep } from "node:path";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { loadFile, parseRoadmap } from "./files.js";
 import { resolveMilestoneFile, milestonesDir, gsdRoot, resolveGsdRootFile, relGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { saveFile } from "./files.js";
-import { listWorktrees, resolveGitDir } from "./worktree-manager.js";
+import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
-import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js";
+import { RUNTIME_EXCLUSION_PATHS, readIntegrationBranch } from "./git-service.js";
+import { nativeIsRepo, nativeBranchExists, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { ensureGitignore } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
@@ -215,6 +215,70 @@ export async function checkGitHealth(
   } catch {
     // git branch list failed — skip
   }
+
+  // ── Integration branch existence ──────────────────────────────────────
+  // For each active (non-complete) milestone, verify the stored integration
+  // branch still exists in git. A missing integration branch blocks merge-back
+  // and causes the next merge operation to fail silently.
+  try {
+    const state = await deriveState(basePath);
+    for (const milestone of state.registry) {
+      if (milestone.status === "complete") continue;
+      const integrationBranch = readIntegrationBranch(basePath, milestone.id);
+      if (!integrationBranch) continue; // No stored branch — skip (not yet set)
+      if (!nativeBranchExists(basePath, integrationBranch)) {
+        issues.push({
+          severity: "error",
+          code: "integration_branch_missing",
+          scope: "milestone",
+          unitId: milestone.id,
+          message: `Milestone ${milestone.id} recorded integration branch "${integrationBranch}" but that branch no longer exists in git. Merge-back will fail.`,
+          fixable: false,
+        });
+      }
+    }
+  } catch {
+    // Non-fatal — integration branch check failed
+  }
+
+  // ── Orphaned worktree directories ────────────────────────────────────
+  // Worktree removal can fail after a branch delete, leaving a directory
+  // that is no longer registered with git. These orphaned dirs cause
+  // "already exists" errors when re-creating the same worktree name.
+  try {
+    const wtDir = worktreesDir(basePath);
+    if (existsSync(wtDir)) {
+      const registeredPaths = new Set(
+        nativeWorktreeList(basePath).map(entry => entry.path),
+      );
+      for (const entry of readdirSync(wtDir)) {
+        const fullPath = join(wtDir, entry);
+        try {
+          if (!statSync(fullPath).isDirectory()) continue;
+        } catch { continue; }
+        if (!registeredPaths.has(fullPath)) {
+          issues.push({
+            severity: "warning",
+            code: "worktree_directory_orphaned",
+            scope: "project",
+            unitId: entry,
+            message: `Worktree directory ${fullPath} exists on disk but is not registered with git. Run "git worktree prune" or doctor --fix to remove it.`,
+            fixable: true,
+          });
+          if (shouldFix("worktree_directory_orphaned")) {
+            try {
+              rmSync(fullPath, { recursive: true, force: true });
+              fixesApplied.push(`removed orphaned worktree directory ${fullPath}`);
+            } catch {
+              fixesApplied.push(`failed to remove orphaned worktree directory ${fullPath}`);
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — orphaned worktree directory check failed
+  }
 }
 
 // ── Runtime Health Checks ──────────────────────────────────────────────────
@@ -255,6 +319,44 @@ export async function checkRuntimeHealth(
     // Non-fatal — crash lock check failed
   }
 
+  // ── Stranded lock directory ────────────────────────────────────────────
+  // proper-lockfile creates a `.gsd.lock/` directory as the OS-level lock
+  // mechanism. If the process was SIGKILLed or crashed hard, this directory
+  // can remain on disk without any live process holding it. The next session
+  // fails to acquire the lock until the directory is removed (#1245).
+  try {
+    const lockDir = join(dirname(root), `${basename(root)}.lock`);
+    if (existsSync(lockDir)) {
+      const statRes = statSync(lockDir);
+      if (statRes.isDirectory()) {
+        // Check if any live process actually holds this lock
+        const lock = readCrashLock(basePath);
+        const lockHolderAlive = lock ? isLockProcessAlive(lock) : false;
+        if (!lockHolderAlive) {
+          issues.push({
+            severity: "error",
+            code: "stranded_lock_directory",
+            scope: "project",
+            unitId: "project",
+            message: `Stranded lock directory "${lockDir}" exists but no live process holds the session lock. This blocks new auto-mode sessions from starting.`,
+            file: lockDir,
+            fixable: true,
+          });
+          if (shouldFix("stranded_lock_directory")) {
+            try {
+              rmSync(lockDir, { recursive: true, force: true });
+              fixesApplied.push(`removed stranded lock directory ${lockDir}`);
+            } catch {
+              fixesApplied.push(`failed to remove stranded lock directory ${lockDir}`);
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — stranded lock directory check failed
+  }
+
   // ── Stale parallel sessions ────────────────────────────────────────────
   try {
     const parallelStatuses = readAllSessionStatuses(basePath);

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

@@ -20,6 +20,9 @@ import { gsdRoot, resolveGsdRootFile } from "./paths.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { rebuildState } from "./doctor.js";
+import { deriveState } from "./state.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { nativeBranchExists, nativeIsRepo } from "./native-git-bridge.js";
 
 // ── Health Score Tracking ──────────────────────────────────────────────────
 
@@ -191,6 +194,27 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
     // Non-fatal — dispatch continues without STATE.md if rebuild fails
   }
 
+  // ── Integration branch existence check ──
+  // If the active milestone's recorded integration branch no longer exists in
+  // git, the merge-back at the end of the milestone will fail. Block dispatch
+  // now to surface this before work is lost.
+  try {
+    if (nativeIsRepo(basePath)) {
+      const state = await deriveState(basePath);
+      if (state.activeMilestone) {
+        const integrationBranch = readIntegrationBranch(basePath, state.activeMilestone.id);
+        if (integrationBranch && !nativeBranchExists(basePath, integrationBranch)) {
+          issues.push(
+            `Integration branch "${integrationBranch}" for milestone ${state.activeMilestone.id} no longer exists in git. ` +
+            `Restore the branch or update the integration branch before dispatching. Run /gsd doctor for details.`,
+          );
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — dispatch continues if state/branch check fails
+  }
+
   // If we had critical issues that couldn't be auto-healed, block dispatch
   if (issues.length > 0) {
     return {

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

@@ -45,7 +45,15 @@ export type DoctorIssueCode =
   | "env_python"
   | "env_cargo"
   | "env_go"
-  | "env_git_remote";
+  | "env_git_remote"
+  // Provider / auth checks
+  | "provider_key_missing"
+  | "provider_key_backedoff"
+  // Lock infrastructure checks
+  | "stranded_lock_directory"
+  // Git / worktree integrity checks
+  | "integration_branch_missing"
+  | "worktree_directory_orphaned";
 
 /**
  * Issue codes that represent expected completion-transition states.

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

@@ -11,6 +11,7 @@ import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
+import { runProviderChecks } from "./doctor-providers.js";
 
 // ── Re-exports ─────────────────────────────────────────────────────────────
 // All public types and functions from extracted modules are re-exported here
@@ -406,6 +407,40 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   issues.push(...auditRequirements(requirementsContent));
 
   const state = await deriveState(basePath);
+
+  // Provider / auth health checks — only relevant when there is active work to dispatch.
+  // Skipped for idle projects (no active milestone) to avoid noise in environments
+  // where CI/test runners have no API key configured.
+  if (state.activeMilestone) {
+    try {
+      const providerResults = runProviderChecks();
+      for (const result of providerResults) {
+        if (!result.required) continue;
+        if (result.status === "error") {
+          issues.push({
+            severity: "warning",
+            code: "provider_key_missing",
+            scope: "project",
+            unitId: "project",
+            message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+            fixable: false,
+          });
+        } else if (result.status === "warning") {
+          issues.push({
+            severity: "warning",
+            code: "provider_key_backedoff",
+            scope: "project",
+            unitId: "project",
+            message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+            fixable: false,
+          });
+        }
+      }
+    } catch {
+      // Non-fatal — provider check failure should not block other checks
+    }
+  }
+
   for (const milestone of state.registry) {
     const milestoneId = milestone.id;
     const milestonePath = resolveMilestonePath(basePath, milestoneId);