gsd-pi 2.34.0 → 2.35.0-dev.34ce717

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

@@ -0,0 +1,55 @@
+/**
+ * /gsd rate — Submit feedback on the last unit's model tier assignment.
+ * Feeds into the adaptive routing history so future dispatches improve.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { loadLedgerFromDisk } from "./metrics.js";
+import { recordFeedback, initRoutingHistory } from "./routing-history.js";
+import type { ComplexityTier } from "./complexity-classifier.js";
+
+const VALID_RATINGS = new Set(["over", "under", "ok"]);
+
+export async function handleRate(
+  args: string,
+  ctx: ExtensionCommandContext,
+  basePath: string,
+): Promise<void> {
+  const rating = args.trim().toLowerCase();
+
+  if (!rating || !VALID_RATINGS.has(rating)) {
+    ctx.ui.notify(
+      "Usage: /gsd rate <over|ok|under>\n" +
+      "  over  — model was overpowered for that task (encourage cheaper)\n" +
+      "  ok    — model was appropriate\n" +
+      "  under — model was too weak (encourage stronger)",
+      "info",
+    );
+    return;
+  }
+
+  const ledger = loadLedgerFromDisk(basePath);
+  if (!ledger || ledger.units.length === 0) {
+    ctx.ui.notify("No completed units found — nothing to rate.", "warning");
+    return;
+  }
+
+  const lastUnit = ledger.units[ledger.units.length - 1];
+  const tier = lastUnit.tier as ComplexityTier | undefined;
+
+  if (!tier) {
+    ctx.ui.notify(
+      "Last unit has no tier data (dynamic routing was not active). Rating skipped.",
+      "warning",
+    );
+    return;
+  }
+
+  initRoutingHistory(basePath);
+  recordFeedback(lastUnit.type, lastUnit.id, tier, rating as "over" | "under" | "ok");
+
+  ctx.ui.notify(
+    `Recorded "${rating}" for ${lastUnit.type}/${lastUnit.id} at tier ${tier}.`,
+    "info",
+  );
+}

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

@@ -48,6 +48,7 @@ import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { handleLogs } from "./commands-logs.js";
 import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -69,9 +70,42 @@ export function projectRoot(): string {
   return root;
 }
 
+/**
+ * Check if another process holds the auto-mode session lock.
+ * Returns the lock data if a remote session is alive, null otherwise.
+ */
+function getRemoteAutoSession(basePath: string): { pid: number } | null {
+  const lockData = readSessionLockData(basePath);
+  if (!lockData) return null;
+  if (lockData.pid === process.pid) return null;
+  if (!isSessionLockProcessAlive(lockData)) return null;
+  return { pid: lockData.pid };
+}
+
+/**
+ * Show a steering menu when auto-mode is running in another process.
+ * Returns true if a remote session was detected (caller should return early).
+ */
+function notifyRemoteAutoActive(ctx: ExtensionCommandContext, basePath: string): boolean {
+  const remote = getRemoteAutoSession(basePath);
+  if (!remote) return false;
+  ctx.ui.notify(
+    `Auto-mode is running in another process (PID ${remote.pid}).\n` +
+    `Use these commands to interact with it:\n` +
+    `  /gsd status   — check progress\n` +
+    `  /gsd discuss  — discuss architecture decisions\n` +
+    `  /gsd queue    — queue the next milestone\n` +
+    `  /gsd steer    — apply an override to active work\n` +
+    `  /gsd capture  — fire-and-forget thought\n` +
+    `  /gsd stop     — stop auto-mode`,
+    "warning",
+  );
+  return true;
+}
+
 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,9 +119,11 @@ 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" },
+        { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
         { cmd: "undo", desc: "Revert last completed unit" },
         { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
         { cmd: "export", desc: "Export milestone/slice results" },
@@ -499,11 +535,18 @@ 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());
           return;
         }
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
@@ -559,6 +602,12 @@ export async function handleGSDCommand(
         return;
       }
 
+      if (trimmed === "rate" || trimmed.startsWith("rate ")) {
+        const { handleRate } = await import("./commands-rate.js");
+        await handleRate(trimmed.replace(/^rate\s*/, "").trim(), ctx, projectRoot());
+        return;
+      }
+
       if (trimmed.startsWith("skip ")) {
         await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
         return;
@@ -892,7 +941,7 @@ Examples:
       }
 
       if (trimmed === "") {
-        // Bare /gsd defaults to step mode
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }
@@ -928,6 +977,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);