gsd-pi 2.34.0 → 2.35.0-dev.30eec3f

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

@@ -0,0 +1,213 @@
+/**
+ * GSD Changelog — Fetch and display categorized release notes from GitHub
+ *
+ * Fetches releases from the gsd-build/gsd-2 GitHub repository,
+ * prompts the user for a version filter, and sends raw release notes
+ * into the conversation for the LLM to summarize.
+ *
+ * Entry point: handleChangelog() called from commands.ts
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface GitHubRelease {
+  tag_name: string;
+  name: string;
+  body: string;
+}
+
+// ─── Semver comparison ────────────────────────────────────────────────────────
+
+function compareSemver(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return 1;
+    if (va < vb) return -1;
+  }
+  return 0;
+}
+
+function stripV(tag: string): string {
+  return tag.startsWith("v") ? tag.slice(1) : tag;
+}
+
+// ─── Body parsing ─────────────────────────────────────────────────────────────
+
+interface CategorySection {
+  heading: string;
+  content: string;
+}
+
+function parseReleaseBody(body: string): CategorySection[] {
+  if (!body) return [];
+
+  const sections: CategorySection[] = [];
+  const lines = body.split("\n");
+  let currentHeading: string | null = null;
+  let currentLines: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith("### ")) {
+      if (currentHeading !== null) {
+        const content = currentLines.join("\n").trim();
+        if (content) {
+          sections.push({ heading: currentHeading, content });
+        }
+      }
+      currentHeading = line.slice(4).trim();
+      currentLines = [];
+    } else if (currentHeading !== null) {
+      currentLines.push(line);
+    }
+  }
+
+  if (currentHeading !== null) {
+    const content = currentLines.join("\n").trim();
+    if (content) {
+      sections.push({ heading: currentHeading, content });
+    }
+  }
+
+  return sections;
+}
+
+// ─── Display formatting ──────────────────────────────────────────────────────
+
+function formatRelease(release: GitHubRelease): string {
+  const version = stripV(release.tag_name);
+  const title = release.name || `v${version}`;
+  const sections = parseReleaseBody(release.body);
+
+  const parts: string[] = [`## ${title}`];
+
+  if (sections.length === 0) {
+    if (release.body?.trim()) {
+      parts.push(release.body.trim());
+    } else {
+      parts.push("_No release notes._");
+    }
+  } else {
+    for (const section of sections) {
+      parts.push(`### ${section.heading}`);
+      parts.push(section.content);
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+// ─── Entry Point ──────────────────────────────────────────────────────────────
+
+const RELEASES_URL = "https://api.github.com/repos/gsd-build/gsd-2/releases?per_page=100";
+
+export async function handleChangelog(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  // ── Fetch releases ──────────────────────────────────────────────────────
+  let releases: GitHubRelease[];
+  try {
+    const response = await fetch(RELEASES_URL, {
+      headers: { "User-Agent": "gsd-changelog" },
+    });
+
+    if (!response.ok) {
+      ctx.ui.notify(
+        `Failed to fetch changelog: GitHub API returned ${response.status} ${response.statusText}`,
+        "error",
+      );
+      return;
+    }
+
+    releases = (await response.json()) as GitHubRelease[];
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to fetch changelog: ${message}`, "error");
+    return;
+  }
+
+  if (!releases.length) {
+    ctx.ui.notify("No releases found in the repository.", "warning");
+    return;
+  }
+
+  // ── Determine version filter ────────────────────────────────────────────
+  const currentVersion = process.env.GSD_VERSION || "";
+  let sinceVersion: string | undefined;
+  let showCurrentOnly = false;
+
+  if (args.trim()) {
+    sinceVersion = stripV(args.trim());
+  } else {
+    const input = await ctx.ui.input(
+      "Show changes since version:",
+      currentVersion || "latest",
+    );
+
+    if (input === undefined) {
+      return;
+    }
+
+    if (input.trim() === "") {
+      showCurrentOnly = true;
+    } else {
+      sinceVersion = stripV(input.trim());
+    }
+  }
+
+  // ── Filter releases ─────────────────────────────────────────────────────
+  let matched: GitHubRelease[];
+
+  if (showCurrentOnly) {
+    if (!currentVersion) {
+      ctx.ui.notify(
+        "GSD_VERSION is not set — cannot determine current release. Provide a version instead.",
+        "warning",
+      );
+      return;
+    }
+    const found = releases.find((r) => stripV(r.tag_name) === currentVersion);
+    if (!found) {
+      ctx.ui.notify(`No release found matching current version v${currentVersion}`, "warning");
+      return;
+    }
+    matched = [found];
+  } else if (sinceVersion) {
+    matched = releases
+      .filter((r) => compareSemver(stripV(r.tag_name), sinceVersion!) > 0)
+      .sort((a, b) => compareSemver(stripV(b.tag_name), stripV(a.tag_name)));
+
+    if (!matched.length) {
+      ctx.ui.notify(`No releases found since v${sinceVersion}`, "warning");
+      return;
+    }
+  } else {
+    matched = [releases[0]];
+  }
+
+  // ── Send to LLM for summarization ───────────────────────────────────────
+  const rawOutput = matched.map(formatRelease).join("\n\n---\n\n");
+  const versionRange = sinceVersion
+    ? `since v${sinceVersion} (${matched.length} release${matched.length === 1 ? "" : "s"})`
+    : `for current release ${matched[0].name || matched[0].tag_name}`;
+
+  const prompt = [
+    `Here are the raw GSD changelog entries ${versionRange}.`,
+    "Summarize the most important changes — group by category (Added, Changed, Fixed, etc.),",
+    "keep only the most impactful items (max 5 per category), skip trivial changes,",
+    "and include the version where each item appeared. Keep it concise and scannable.",
+    "",
+    rawOutput,
+  ].join("\n");
+
+  pi.sendMessage(
+    { customType: "gsd-changelog", content: prompt, display: true },
+    { triggerTurn: true },
+  );
+}

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

@@ -12,6 +12,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
   { cmd: "capture", desc: "Fire-and-forget thought capture" },
+  { cmd: "changelog", desc: "Show categorized release notes" },
   { cmd: "triage", desc: "Manually trigger triage of pending captures" },
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
   { cmd: "history", desc: "View execution history" },

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

@@ -24,7 +24,7 @@ import { projectRoot } from "./commands.js";
 import { loadPrompt } from "./prompt-loader.js";
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
     doctorSummary: reportText,
@@ -187,7 +187,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
     roadmapContext: roadmapContext || "(no active roadmap)",
   });
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(

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

@@ -5,6 +5,9 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { getErrorMessage } from "./error-utils.js";
 
 export interface InspectData {
@@ -44,11 +47,15 @@ export function formatInspectOutput(data: InspectData): string {
 
 export async function handleInspect(ctx: ExtensionCommandContext): Promise<void> {
   try {
-    const { isDbAvailable, _getAdapter } = await import("./gsd-db.js");
+    const { isDbAvailable, _getAdapter, openDatabase } = await import("./gsd-db.js");
 
     if (!isDbAvailable()) {
-      ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
-      return;
+      const gsdDir = gsdRoot(process.cwd());
+      const dbPath = join(gsdDir, "gsd.db");
+      if (!existsSync(gsdDir) || !existsSync(dbPath) || !openDatabase(dbPath)) {
+        ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
+        return;
+      }
     }
 
     const adapter = _getAdapter();

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/commands.ts

@@ -71,7 +71,7 @@ export function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel|update",
+    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -85,6 +85,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
         { cmd: "discuss", desc: "Discuss architecture and decisions" },
         { cmd: "capture", desc: "Fire-and-forget thought capture" },
+        { cmd: "changelog", desc: "Show categorized release notes" },
         { cmd: "triage", desc: "Manually trigger triage of pending captures" },
         { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
         { cmd: "history", desc: "View execution history" },
@@ -499,6 +500,12 @@ export async function handleGSDCommand(
         return;
       }
 
+      if (trimmed === "changelog" || trimmed.startsWith("changelog ")) {
+        const { handleChangelog } = await import("./changelog.js");
+        await handleChangelog(trimmed.replace(/^changelog\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
       if (trimmed === "next" || trimmed.startsWith("next ")) {
         if (trimmed.includes("--dry-run")) {
           await handleDryRun(ctx, projectRoot());
@@ -928,6 +935,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /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]",
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",

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-environment.ts

@@ -180,26 +180,36 @@ function checkPortConflicts(basePath: string): EnvironmentCheckResult[] {
   const portsToCheck = new Set<number>();
   const pkgPath = join(basePath, "package.json");
 
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const scripts = pkg.scripts ?? {};
-      const scriptText = Object.values(scripts).join(" ");
-
-      // Look for --port NNNN, -p NNNN, PORT=NNNN, :NNNN patterns
-      const portMatches = scriptText.matchAll(/(?:--port\s+|(?:^|[^a-z])PORT[=:]\s*|-p\s+|:)(\d{4,5})\b/gi);
-      for (const m of portMatches) {
-        const port = parseInt(m[1], 10);
-        if (port >= 1024 && port <= 65535) portsToCheck.add(port);
-      }
-    } catch {
-      // parse failed — use defaults
+  if (!existsSync(pkgPath)) {
+    // No package.json — this isn't a Node.js project. Skip port checks
+    // entirely to avoid false positives from system services (e.g., macOS
+    // AirPlay Receiver on port 5000). (#1381)
+    return [];
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const scripts = pkg.scripts ?? {};
+    const scriptText = Object.values(scripts).join(" ");
+
+    // Look for --port NNNN, -p NNNN, PORT=NNNN, :NNNN patterns
+    const portMatches = scriptText.matchAll(/(?:--port\s+|(?:^|[^a-z])PORT[=:]\s*|-p\s+|:)(\d{4,5})\b/gi);
+    for (const m of portMatches) {
+      const port = parseInt(m[1], 10);
+      if (port >= 1024 && port <= 65535) portsToCheck.add(port);
     }
+  } catch {
+    // parse failed — skip port checks rather than using defaults
+    return [];
   }
 
-  // If no ports found in scripts, check common defaults
+  // If no ports found in scripts, check common defaults.
+  // Filter out port 5000 on macOS — AirPlay Receiver uses it by default (#1381).
   if (portsToCheck.size === 0) {
-    for (const p of DEFAULT_DEV_PORTS) portsToCheck.add(p);
+    for (const p of DEFAULT_DEV_PORTS) {
+      if (p === 5000 && process.platform === "darwin") continue;
+      portsToCheck.add(p);
+    }
   }
 
   for (const port of portsToCheck) {

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);