gsd-pi 2.34.0 → 2.35.0-dev.34ce717

package/dist/resources/extensions/gsd/changelog.js

@@ -0,0 +1,162 @@
+/**
+ * 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
+ */
+// ─── Semver comparison ────────────────────────────────────────────────────────
+function compareSemver(a, b) {
+    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) {
+    return tag.startsWith("v") ? tag.slice(1) : tag;
+}
+function parseReleaseBody(body) {
+    if (!body)
+        return [];
+    const sections = [];
+    const lines = body.split("\n");
+    let currentHeading = null;
+    let currentLines = [];
+    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) {
+    const version = stripV(release.tag_name);
+    const title = release.name || `v${version}`;
+    const sections = parseReleaseBody(release.body);
+    const parts = [`## ${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, ctx, pi) {
+    // ── Fetch releases ──────────────────────────────────────────────────────
+    let releases;
+    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());
+    }
+    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;
+    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;
+    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/dist/resources/extensions/gsd/commands-bootstrap.js

@@ -11,6 +11,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/dist/resources/extensions/gsd/commands-handlers.js

@@ -15,7 +15,7 @@ import { isAutoActive } from "./auto.js";
 import { projectRoot } from "./commands.js";
 import { loadPrompt } from "./prompt-loader.js";
 export function dispatchDoctorHeal(pi, scope, reportText, structuredIssues) {
-    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,
@@ -144,7 +144,7 @@ export async function handleTriage(ctx, pi, basePath) {
         currentPlan: currentPlan || "(no active slice plan)",
         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({
         customType: "gsd-triage",

package/dist/resources/extensions/gsd/commands-inspect.js

@@ -3,6 +3,9 @@
  *
  * Contains: InspectData type, formatInspectOutput, handleInspect
  */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { getErrorMessage } from "./error-utils.js";
 export function formatInspectOutput(data) {
     const lines = [];
@@ -30,10 +33,14 @@ export function formatInspectOutput(data) {
 }
 export async function handleInspect(ctx) {
     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();
         if (!adapter) {

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -624,10 +624,14 @@ export function serializePreferencesToFrontmatter(prefs) {
     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();
     for (const key of orderedKeys) {

package/dist/resources/extensions/gsd/commands-rate.js

@@ -0,0 +1,31 @@
+/**
+ * /gsd rate — Submit feedback on the last unit's model tier assignment.
+ * Feeds into the adaptive routing history so future dispatches improve.
+ */
+import { loadLedgerFromDisk } from "./metrics.js";
+import { recordFeedback, initRoutingHistory } from "./routing-history.js";
+const VALID_RATINGS = new Set(["over", "under", "ok"]);
+export async function handleRate(args, ctx, basePath) {
+    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;
+    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);
+    ctx.ui.notify(`Recorded "${rating}" for ${lastUnit.type}/${lastUnit.id} at tier ${tier}.`, "info");
+}

package/dist/resources/extensions/gsd/commands.js

@@ -36,6 +36,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. */
 export function projectRoot() {
     const cwd = process.cwd();
@@ -54,9 +55,41 @@ export function projectRoot() {
     }
     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) {
+    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, basePath) {
+    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) {
     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) => {
             const subcommands = [
                 { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -70,9 +103,11 @@ export function registerGSDCommand(pi) {
                 { 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" },
@@ -448,11 +483,18 @@ export async function handleGSDCommand(args, ctx, pi) {
         await handleForensics(trimmed.replace(/^forensics\s*/, "").trim(), ctx, pi);
         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)
@@ -507,6 +549,11 @@ export async function handleGSDCommand(args, ctx, pi) {
         await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
         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;
@@ -803,7 +850,8 @@ Examples:
         return;
     }
     if (trimmed === "") {
-        // Bare /gsd defaults to step mode
+        if (notifyRemoteAutoActive(ctx, projectRoot()))
+            return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
     }
@@ -833,6 +881,7 @@ function showHelp(ctx) {
         "  /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/dist/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/dist/resources/extensions/gsd/doctor-checks.js

@@ -1,13 +1,13 @@
-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 { loadFile, parseRoadmap } from "./files.js";
 import { resolveMilestoneFile, milestonesDir, gsdRoot, resolveGsdRootFile } 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";
@@ -200,6 +200,75 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
     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 ──────────────────────────────────────────────────
 // Checks for stale crash locks, orphaned completed-units, stale hook state,
@@ -231,6 +300,45 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
     catch {
         // 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/dist/resources/extensions/gsd/doctor-environment.js

@@ -148,27 +148,36 @@ function checkPortConflicts(basePath) {
     // Try to detect ports from package.json scripts
     const portsToCheck = new Set();
     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);
         }
     }
-    // If no ports found in scripts, check common defaults
+    catch {
+        // parse failed — skip port checks rather than using defaults
+        return [];
+    }
+    // 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)
+        for (const p of DEFAULT_DEV_PORTS) {
+            if (p === 5000 && process.platform === "darwin")
+                continue;
             portsToCheck.add(p);
+        }
     }
     for (const port of portsToCheck) {
         const result = tryExec(`lsof -i :${port} -sTCP:LISTEN -t`, basePath);

package/dist/resources/extensions/gsd/doctor-proactive.js

@@ -19,6 +19,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";
 /** In-memory health history for the current auto-mode session. */
 let healthHistory = [];
 /** Count of consecutive units with unresolved errors. */
@@ -156,6 +159,25 @@ export async function preDispatchHealthGate(basePath) {
     catch {
         // 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 {