gsd-pi 2.78.0 → 2.78.1-dev.82bcf6b71

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -39,6 +39,11 @@ import {
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
+import {
+  isGsdWorktreePath,
+  normalizeWorktreePathForCompare,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -75,6 +80,20 @@ function normalizePathForComparison(path: string): string {
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
+function normalizeBasePathForWorktreeOps(basePath: string): string {
+  const resolved = resolveWorktreeProjectRoot(basePath);
+  if (
+    isGsdWorktreePath(basePath) &&
+    normalizeWorktreePathForCompare(resolved) === normalizeWorktreePathForCompare(basePath)
+  ) {
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Cannot resolve project root from worktree path: ${basePath}. Run the command from the project root or set GSD_PROJECT_ROOT.`,
+    );
+  }
+  return resolved;
+}
+
 // ─── resolveGitDir ─────────────────────────────────────────────────────────
 
 /**
@@ -106,7 +125,7 @@ export function resolveGitDir(basePath: string): string {
 }
 
 export function worktreesDir(basePath: string): string {
-  return join(basePath, ".gsd", "worktrees");
+  return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
 }
 
 export function worktreePath(basePath: string, name: string): string {
@@ -195,6 +214,8 @@ export function resolveCanonicalMilestoneRoot(
  * @param opts.branch — override the default `worktree/<name>` branch name
  */
 export function createWorktree(basePath: string, name: string, opts: { branch?: string; startPoint?: string; reuseExistingBranch?: boolean } = {}): WorktreeInfo {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   // Validate name: alphanumeric, hyphens, underscores only
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
     throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
@@ -297,6 +318,8 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
  * Uses native worktree list and filters to those under .gsd/worktrees/.
  */
 export function listWorktrees(basePath: string): WorktreeInfo[] {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const baseVariants = [resolve(basePath)];
   if (existsSync(basePath)) {
     baseVariants.push(realpathSync(basePath));
@@ -459,6 +482,8 @@ export function removeWorktree(
   name: string,
   opts: { deleteBranch?: boolean; force?: boolean; branch?: string } = {},
 ): void {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   let wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
   const { deleteBranch = true, force = true } = opts;
@@ -714,6 +739,8 @@ function parseDiffNameStatus(entries: { status: string; path: string }[]): Workt
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
 export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSummary {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -729,6 +756,8 @@ export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSum
  * content, this correctly returns an empty diff.
  */
 export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSummary {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -742,6 +771,8 @@ export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSum
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
 export function diffWorktreeNumstat(basePath: string, name: string): FileLineStat[] {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -760,6 +791,8 @@ export function diffWorktreeNumstat(basePath: string, name: string): FileLineSta
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeGSDDiff(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -771,6 +804,8 @@ export function getWorktreeGSDDiff(basePath: string, name: string): string {
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeCodeDiff(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -781,6 +816,8 @@ export function getWorktreeCodeDiff(basePath: string, name: string): string {
  * Get commit log for the worktree branch since it diverged from main.
  */
 export function getWorktreeLog(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -795,6 +832,8 @@ export function getWorktreeLog(basePath: string, name: string): string {
  * Returns the merge commit message.
  */
 export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
   const current = nativeGetCurrentBranch(basePath);

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -23,6 +23,7 @@ import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
@@ -84,31 +85,20 @@ export interface NotifyCtx {
 
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 
-/**
- * Worktree marker segment — present in any path produced by worktreePath().
- * Used to strip the worktree suffix and recover the project root (#3729).
- */
-const WORKTREE_MARKER = "/.gsd/worktrees/";
-
 /**
  * Resolve the project root from session path state.
  *
  * Prefers `originalBasePath` (always the project root when set), but falls
  * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
  * with default empty string). If `basePath` itself is inside a worktree
- * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
- * actual project root — preventing double-nested worktree paths (#3729).
+ * directory (including symlink-resolved ~/.gsd/projects/<hash>/worktrees
+ * paths), recover the actual project root to prevent double nesting (#3729).
  */
 export function resolveProjectRoot(
   originalBasePath: string,
   basePath: string,
 ): string {
-  let resolved = originalBasePath || basePath;
-  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
-  if (markerIdx !== -1) {
-    resolved = resolved.slice(0, markerIdx);
-  }
-  return resolved;
+  return resolveWorktreeProjectRoot(basePath, originalBasePath);
 }
 
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
@@ -414,6 +404,30 @@ export class WorktreeResolver {
   mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
 
+    // Anchor cwd at the project root before any merge work. Some merge code
+    // paths (mergeMilestoneToMain, slice-cadence) chdir explicitly; others
+    // (branch-mode, isolation-degraded skip, missing-original-base skip)
+    // do not. If the worktree dir is later torn down while cwd still points
+    // into it, every subsequent process.cwd() throws ENOENT — and after
+    // de73fb43d that surfaces as a session-failed cancel and (in headless
+    // mode) terminates the whole gsd process. Best-effort: silent on
+    // failure so existing test fixtures that use synthetic paths still pass.
+    if (this.s.originalBasePath) {
+      try {
+        // process.cwd() can throw ENOENT when cwd was removed, so attempt
+        // recovery directly.
+        process.chdir(this.s.originalBasePath);
+      } catch (err) {
+        debugLog("WorktreeResolver", {
+          action: "mergeAndExit",
+          phase: "pre-merge-chdir-failed",
+          milestoneId,
+          originalBasePath: this.s.originalBasePath,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     // #4764 — telemetry: record start timestamp so we can emit merge duration.
     const mergeStartedAt = new Date().toISOString();
     const mergeStartMs = Date.now();

package/src/resources/extensions/gsd/worktree-root.ts

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface WorktreeSegment {
+  gsdIdx: number;
+  afterWorktrees: number;
+}
+
+export function normalizeWorktreePathForCompare(path: string): string {
+  let normalized: string;
+  try {
+    normalized = realpathSync(path);
+  } catch {
+    normalized = resolve(path);
+  }
+  const slashed = normalized.replaceAll("\\", "/");
+  const trimmed = slashed.replace(/\/+$/, "");
+  return process.platform === "win32" ? (trimmed || "/").toLowerCase() : (trimmed || "/");
+}
+
+/**
+ * Find the GSD worktree segment in both direct project layout and the
+ * symlink-resolved external-state layout used by ~/.gsd/projects/<hash>.
+ */
+export function findWorktreeSegment(normalizedPath: string): WorktreeSegment | null {
+  const directMarker = "/.gsd/worktrees/";
+  const directIdx = normalizedPath.indexOf(directMarker);
+  if (directIdx !== -1) {
+    return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
+  }
+
+  const externalRe = /\/\.gsd\/projects\/[^/]+\/worktrees\//;
+  const externalMatch = normalizedPath.match(externalRe);
+  if (externalMatch && externalMatch.index !== undefined) {
+    return {
+      gsdIdx: externalMatch.index,
+      afterWorktrees: externalMatch.index + externalMatch[0].length,
+    };
+  }
+
+  return null;
+}
+
+export function isGsdWorktreePath(path: string): boolean {
+  return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
+}
+
+/**
+ * Resolve the canonical project root for worktree operations.
+ *
+ * `originalBasePath` wins when available because session state already knows the
+ * root. `GSD_PROJECT_ROOT` is the next strongest signal for worker processes.
+ * Otherwise, derive the root from direct `.gsd/worktrees` paths, or recover it
+ * from the worktree `.git` file for symlink-resolved ~/.gsd/project paths.
+ */
+export function resolveWorktreeProjectRoot(
+  basePath: string,
+  originalBasePath?: string | null,
+): string {
+  const preferred =
+    originalBasePath?.trim() ||
+    process.env.GSD_PROJECT_ROOT?.trim() ||
+    basePath;
+
+  return resolveProjectRootFromPath(preferred);
+}
+
+function resolveProjectRootFromPath(path: string): string {
+  const normalizedPath = path.replaceAll("\\", "/");
+  const segment = findWorktreeSegment(normalizedPath);
+  if (!segment) return resolveGitWorkingTreeRoot(path) ?? path;
+
+  const sepChar = path.includes("\\") ? "\\" : "/";
+  const gsdMarker = `${sepChar}.gsd${sepChar}`;
+  const markerIdx = path.indexOf(gsdMarker);
+  const candidate = markerIdx !== -1
+    ? path.slice(0, markerIdx)
+    : path.slice(0, segment.gsdIdx);
+
+  const gsdHome = normalizeWorktreePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
+  const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
+
+  if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(`${gsdHome}/`)) {
+    const realRoot = resolveProjectRootFromGitFile(path);
+    return realRoot ?? path;
+  }
+
+  return candidate;
+}
+
+function resolveGitWorkingTreeRoot(path: string): string | null {
+  try {
+    let dir = existsSync(path) && !statSync(path).isDirectory()
+      ? resolve(path, "..")
+      : path;
+
+    for (let i = 0; i < 30; i++) {
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) return dir;
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers either keep the original path or fail closed.
+  }
+  return null;
+}
+
+function resolveProjectRootFromGitFile(worktreePath: string): string | null {
+  try {
+    let dir = worktreePath;
+    for (let i = 0; i < 30; i++) {
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) {
+        const content = readFileSync(gitPath, "utf8").trim();
+        if (content.startsWith("gitdir: ")) {
+          const gitDir = resolve(dir, content.slice(8));
+          const dotGitDir = resolve(gitDir, "..", "..");
+          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
+            return resolve(dotGitDir, "..");
+          }
+
+          const commonDirPath = join(gitDir, "commondir");
+          if (existsSync(commonDirPath)) {
+            const commonDir = readFileSync(commonDirPath, "utf8").trim();
+            const resolvedCommonDir = resolve(gitDir, commonDir);
+            return resolve(resolvedCommonDir, "..");
+          }
+        }
+        break;
+      }
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers either keep the original path or fail closed.
+  }
+  return null;
+}

package/src/resources/extensions/gsd/worktree-session-state.ts

@@ -0,0 +1,35 @@
+// GSD worktree session state
+let originalCwd: string | null = null;
+
+export function getWorktreeOriginalCwd(): string | null {
+  return originalCwd;
+}
+
+export function setWorktreeOriginalCwd(cwd: string): void {
+  originalCwd = cwd;
+}
+
+export function clearWorktreeOriginalCwd(): void {
+  originalCwd = null;
+}
+
+export function ensureWorktreeOriginalCwdFromPath(cwd: string = process.cwd()): string | null {
+  if (originalCwd) return originalCwd;
+  const marker = `${/\\/.test(cwd) ? "\\" : "/"}.gsd${/\\/.test(cwd) ? "\\" : "/"}worktrees${/\\/.test(cwd) ? "\\" : "/"}`;
+  const markerIdx = cwd.indexOf(marker);
+  if (markerIdx !== -1) {
+    originalCwd = cwd.slice(0, markerIdx);
+  }
+  return originalCwd;
+}
+
+export function getActiveWorktreeName(): string | null {
+  if (!originalCwd) return null;
+  const cwd = process.cwd();
+  const wtDir = `${originalCwd.replace(/[\\/]+$/, "")}/.gsd/worktrees`.replaceAll("\\", "/");
+  const normalizedCwd = cwd.replaceAll("\\", "/");
+  if (!normalizedCwd.startsWith(`${wtDir}/`)) return null;
+  const rel = normalizedCwd.slice(wtDir.length + 1);
+  const name = rel.split("/")[0];
+  return name || null;
+}

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

@@ -12,12 +12,16 @@
  * SLICE_BRANCH_RE) remain for backwards compatibility with legacy branches.
  */
 
-import { existsSync, readFileSync, realpathSync, utimesSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
-import { homedir } from "node:os";
+import { existsSync, readFileSync, utimesSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 import { GitServiceImpl, writeIntegrationBranch, type TaskCommitContext } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import {
+  findWorktreeSegment,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
+export { resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 export { MergeConflictError } from "./git-service.js";
 export type { TaskCommitContext } from "./git-service.js";
@@ -78,29 +82,6 @@ export function captureIntegrationBranch(basePath: string, milestoneId: string):
 
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
 
-/**
- * Find the worktrees segment in a path, supporting both direct
- * (`/.gsd/worktrees/`) and symlink-resolved (`/.gsd/projects/<hash>/worktrees/`)
- * layouts.  When `.gsd` is a symlink to `~/.gsd/projects/<hash>`, resolved
- * paths contain the intermediate `projects/<hash>/` segment that the old
- * single-marker check missed.
- */
-function findWorktreeSegment(normalizedPath: string): { gsdIdx: number; afterWorktrees: number } | null {
-  // Direct layout: /.gsd/worktrees/<name>
-  const directMarker = "/.gsd/worktrees/";
-  const idx = normalizedPath.indexOf(directMarker);
-  if (idx !== -1) {
-    return { gsdIdx: idx, afterWorktrees: idx + directMarker.length };
-  }
-  // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/<name>
-  const symlinkRe = /\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//;
-  const match = normalizedPath.match(symlinkRe);
-  if (match && match.index !== undefined) {
-    return { gsdIdx: match.index, afterWorktrees: match.index + match[0].length };
-  }
-  return null;
-}
-
 /**
  * Detect the active worktree name from the current working directory.
  * Returns null if not inside a GSD worktree (.gsd/worktrees/<name>/).
@@ -133,99 +114,7 @@ export function detectWorktreeName(basePath: string): string | null {
  * operate against the real project root, not a worktree subdirectory.
  */
 export function resolveProjectRoot(basePath: string): string {
-  // Layer 1: If the coordinator passed the real project root, use it.
-  if (process.env.GSD_PROJECT_ROOT) {
-    return process.env.GSD_PROJECT_ROOT;
-  }
-
-  const normalizedPath = basePath.replaceAll("\\", "/");
-  const seg = findWorktreeSegment(normalizedPath);
-  if (!seg) return basePath;
-
-  // Candidate root via the string-slice heuristic
-  const sepChar = basePath.includes("\\") ? "\\" : "/";
-  const gsdMarker = `${sepChar}.gsd${sepChar}`;
-  const gsdIdx = basePath.indexOf(gsdMarker);
-  const candidate = gsdIdx !== -1
-    ? basePath.slice(0, gsdIdx)
-    : basePath.slice(0, seg.gsdIdx);
-
-  // Layer 2: Guard against resolving to the user's home directory.
-  // When .gsd is a symlink into ~/.gsd/projects/<hash>, the resolved path
-  // contains /.gsd/ at the user-level boundary. Slicing there yields ~ — wrong.
-  const gsdHome = normalizePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
-  const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
-
-  if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(gsdHome + "/")) {
-    // The candidate is the home directory (or within it in a way that .gsd
-    // maps to the user-level GSD dir). Try to recover the real project root
-    // from the worktree's .git file.
-    const realRoot = resolveProjectRootFromGitFile(basePath);
-    if (realRoot) return realRoot;
-    // If git file resolution failed, return basePath unchanged rather than ~
-    return basePath;
-  }
-
-  return candidate;
-}
-
-/**
- * Recover the real project root from a worktree's .git file.
- *
- * Each git worktree has a `.git` file (not directory) containing:
- *   gitdir: /real/project/.git/worktrees/<name>
- *
- * Walking up from that gitdir gives us `/real/project/.git`, and its
- * parent is the real project root.
- */
-function resolveProjectRootFromGitFile(worktreePath: string): string | null {
-  try {
-    // Walk up from the worktree path to find the .git file
-    let dir = worktreePath;
-    for (let i = 0; i < 30; i++) {
-      const gitPath = join(dir, ".git");
-      if (existsSync(gitPath)) {
-        const content = readFileSync(gitPath, "utf8").trim();
-        if (content.startsWith("gitdir: ")) {
-          // gitdir points to: <real-project>/.git/worktrees/<name>
-          const gitDir = resolve(dir, content.slice(8));
-          // Walk up: .git/worktrees/<name> → .git/worktrees → .git → project root
-          const dotGitDir = resolve(gitDir, "..", "..");
-          // Verify this looks like a .git directory
-          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
-            return resolve(dotGitDir, "..");
-          }
-          // Alternative: the commondir file inside the worktree gitdir
-          // points to the main .git directory
-          const commonDirPath = join(gitDir, "commondir");
-          if (existsSync(commonDirPath)) {
-            const commonDir = readFileSync(commonDirPath, "utf8").trim();
-            const resolvedCommonDir = resolve(gitDir, commonDir);
-            return resolve(resolvedCommonDir, "..");
-          }
-        }
-        break;
-      }
-      const parent = resolve(dir, "..");
-      if (parent === dir) break;
-      dir = parent;
-    }
-  } catch {
-    // Non-fatal — caller will use fallback
-  }
-  return null;
-}
-
-function normalizePathForCompare(path: string): string {
-  let normalized: string;
-  try {
-    normalized = realpathSync(path);
-  } catch {
-    normalized = resolve(path);
-  }
-  const slashed = normalized.replaceAll("\\", "/");
-  const trimmed = slashed.replace(/\/+$/, "");
-  return trimmed || "/";
+  return resolveWorktreeProjectRoot(basePath);
 }
 
 /**

package/src/resources/extensions/mcp-client/index.ts

@@ -2,7 +2,8 @@
  * MCP Client Extension — Native MCP server integration for pi
  *
  * Provides on-demand access to MCP servers configured in project files
- * (.mcp.json, .gsd/mcp.json) using the @modelcontextprotocol/sdk Client
+ * (.mcp.json, .gsd/mcp.json) and the global ~/.gsd/mcp.json (or
+ * $GSD_HOME/mcp.json) using the @modelcontextprotocol/sdk Client
  * directly — no external CLI dependency required.
  *
  * Three tools:
@@ -24,6 +25,7 @@ import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildHttpTransportOpts } from "./auth.js";
 import type { McpHttpAuthConfig } from "./auth.js";
@@ -102,6 +104,7 @@ function readConfigs(): McpServerConfig[] {
 	const configPaths = [
 		join(process.cwd(), ".mcp.json"),
 		join(process.cwd(), ".gsd", "mcp.json"),
+		join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
 	];
 
 	for (const configPath of configPaths) {
@@ -321,7 +324,7 @@ async function closeAll(): Promise<void> {
 // ─── Formatters ───────────────────────────────────────────────────────────────
 
 function formatServerList(servers: McpServerConfig[]): string {
-	if (servers.length === 0) return "No MCP servers configured. Add servers to .mcp.json or .gsd/mcp.json.";
+	if (servers.length === 0) return "No MCP servers configured. Add servers to .mcp.json, .gsd/mcp.json, or $GSD_HOME/mcp.json (default: ~/.gsd/mcp.json).";
 
 	const lines: string[] = [`${servers.length} MCP servers configured:\n`];
 
@@ -384,7 +387,7 @@ export default function (pi: ExtensionAPI) {
 		name: "mcp_servers",
 		label: "MCP Servers",
 		description:
-			"List all available MCP servers configured in project files (.mcp.json, .gsd/mcp.json). " +
+			"List all available MCP servers configured in project files (.mcp.json, .gsd/mcp.json) or globally ($GSD_HOME/mcp.json, default: ~/.gsd/mcp.json). " +
 			"Shows server names, transport type, and connection status. Use mcp_discover to get full tool schemas for a server.",
 		promptSnippet:
 			"List available MCP servers from project configuration",
@@ -624,13 +627,6 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Lifecycle ─────────────────────────────────────────────────────────────
 
-	pi.on("session_start", async (_event, ctx) => {
-		const servers = readConfigs();
-		if (servers.length > 0) {
-			ctx.ui.notify(`MCP client ready — ${servers.length} server(s) configured`, "info");
-		}
-	});
-
 	pi.on("session_shutdown", async () => {
 		await closeAll();
 	});

package/src/resources/extensions/mcp-client/tests/global-config.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Regression test for #4757 — readConfigs() must also read the global
+ * ~/.gsd/mcp.json (resolved as $GSD_HOME/mcp.json when GSD_HOME is set).
+ *
+ * Behaviour test against the exported getServerConfig — no source grep.
+ * The fixture is anchored via $GSD_HOME so the test never touches the
+ * developer's real ~/.gsd directory.
+ */
+
+import test, { before, after } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { getServerConfig } from "../index.js";
+
+let cwdDir: string;
+let gsdHomeDir: string;
+let originalCwd: string;
+let originalGsdHome: string | undefined;
+
+before(() => {
+	originalCwd = process.cwd();
+	originalGsdHome = process.env.GSD_HOME;
+
+	// realpathSync resolves any symlink in tmpdir() — on macOS /var → /private/var
+	// so process.cwd() after chdir matches what mkdtempSync returned.
+	cwdDir = realpathSync(mkdtempSync(join(tmpdir(), "mcp-cwd-")));
+	gsdHomeDir = realpathSync(mkdtempSync(join(tmpdir(), "mcp-gsdhome-")));
+
+	// Project-local fixture (also defines `shared-server` for the precedence test)
+	writeFileSync(
+		join(cwdDir, ".mcp.json"),
+		JSON.stringify({
+			mcpServers: {
+				"project-server": { command: "echo", args: ["proj"] },
+				"shared-server": { command: "echo", args: ["from-project"] },
+			},
+		}),
+		"utf-8",
+	);
+
+	// Global fixture rooted at $GSD_HOME (also defines `shared-server` to test
+	// that project-local takes precedence on name collision)
+	writeFileSync(
+		join(gsdHomeDir, "mcp.json"),
+		JSON.stringify({
+			mcpServers: {
+				"global-server": { command: "echo", args: ["glob"] },
+				"shared-server": { command: "echo", args: ["from-global"] },
+			},
+		}),
+		"utf-8",
+	);
+
+	process.chdir(cwdDir);
+	process.env.GSD_HOME = gsdHomeDir;
+});
+
+after(() => {
+	process.chdir(originalCwd);
+	if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+	else process.env.GSD_HOME = originalGsdHome;
+	try { rmSync(cwdDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+	try { rmSync(gsdHomeDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+});
+
+test("#4757: getServerConfig resolves servers declared in $GSD_HOME/mcp.json", () => {
+	const cfg = getServerConfig("global-server");
+	assert.ok(cfg, "server defined in $GSD_HOME/mcp.json must resolve");
+	assert.equal(cfg?.name, "global-server");
+	assert.equal(cfg?.sourcePath, join(gsdHomeDir, "mcp.json"));
+});
+
+test("#4757: project-local servers still resolve when global config exists", () => {
+	const cfg = getServerConfig("project-server");
+	assert.ok(cfg, "project-local server must continue to resolve");
+	assert.equal(cfg?.sourcePath, join(cwdDir, ".mcp.json"));
+});
+
+test("#4757: project-local config wins on server-name collision", () => {
+	const cfg = getServerConfig("shared-server");
+	assert.ok(cfg, "shared server must resolve");
+	assert.equal(
+		cfg?.sourcePath,
+		join(cwdDir, ".mcp.json"),
+		"project-local config must take precedence over $GSD_HOME on name collision",
+	);
+	assert.deepEqual(cfg?.args, ["from-project"]);
+});