gsd-pi 2.35.0 → 2.36.0-dev.d612764

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

@@ -0,0 +1,143 @@
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { clearCmuxSidebar, CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } from "../cmux/index.js";
+import { saveFile } from "./files.js";
+import {
+  getProjectGSDPreferencesPath,
+  loadEffectiveGSDPreferences,
+  loadProjectGSDPreferences,
+} from "./preferences.js";
+import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+
+function extractBodyAfterFrontmatter(content: string): string | null {
+  const start = content.startsWith("---\n") ? 4 : content.startsWith("---\r\n") ? 5 : -1;
+  if (start === -1) return null;
+  const closingIdx = content.indexOf("\n---", start);
+  if (closingIdx === -1) return null;
+  const after = content.slice(closingIdx + 4);
+  return after.trim() ? after : null;
+}
+
+async function writeProjectCmuxPreferences(
+  ctx: ExtensionCommandContext,
+  updater: (prefs: Record<string, unknown>) => void,
+): Promise<void> {
+  const path = getProjectGSDPreferencesPath();
+  await ensurePreferencesFile(path, ctx, "project");
+
+  const existing = loadProjectGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+  updater(prefs);
+  prefs.version = prefs.version || 1;
+
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  if (existsSync(path)) {
+    const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8"));
+    if (preserved) body = preserved;
+  }
+
+  await saveFile(path, `---\n${frontmatter}---${body}`);
+  await ctx.waitForIdle();
+  await ctx.reload();
+}
+
+function formatCmuxStatus(): string {
+  const loaded = loadEffectiveGSDPreferences();
+  const detected = detectCmuxEnvironment();
+  const resolved = resolveCmuxConfig(loaded?.preferences);
+  const capabilities = new CmuxClient(resolved).getCapabilities() as Record<string, unknown> | null;
+  const accessMode = typeof capabilities?.mode === "string"
+    ? capabilities.mode
+    : typeof capabilities?.access_mode === "string"
+      ? capabilities.access_mode
+      : "unknown";
+  const methods = Array.isArray(capabilities?.methods) ? capabilities.methods.length : 0;
+
+  return [
+    "cmux status",
+    "",
+    `Detected: ${detected.available ? "yes" : "no"}`,
+    `Enabled: ${resolved.enabled ? "yes" : "no"}`,
+    `CLI available: ${detected.cliAvailable ? "yes" : "no"}`,
+    `Socket: ${detected.socketPath}`,
+    `Workspace: ${detected.workspaceId ?? "(none)"}`,
+    `Surface: ${detected.surfaceId ?? "(none)"}`,
+    `Features: notifications=${resolved.notifications ? "on" : "off"}, sidebar=${resolved.sidebar ? "on" : "off"}, splits=${resolved.splits ? "on" : "off"}, browser=${resolved.browser ? "on" : "off"}`,
+    `Capabilities: access=${accessMode}, methods=${methods}`,
+  ].join("\n");
+}
+
+function ensureCmuxAvailableForEnable(ctx: ExtensionCommandContext): boolean {
+  const detected = detectCmuxEnvironment();
+  if (detected.available) return true;
+  ctx.ui.notify(
+    "cmux not detected. Install it from https://cmux.com and run gsd inside a cmux terminal.",
+    "warning",
+  );
+  return false;
+}
+
+export async function handleCmux(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const trimmed = args.trim();
+  if (!trimmed || trimmed === "status") {
+    ctx.ui.notify(formatCmuxStatus(), "info");
+    return;
+  }
+
+  if (trimmed === "on") {
+    if (!ensureCmuxAvailableForEnable(ctx)) return;
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      prefs.cmux = {
+        enabled: true,
+        notifications: true,
+        sidebar: true,
+        splits: false,
+        browser: false,
+        ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}),
+      };
+      (prefs.cmux as Record<string, unknown>).enabled = true;
+    });
+    ctx.ui.notify("cmux integration enabled in project preferences.", "info");
+    return;
+  }
+
+  if (trimmed === "off") {
+    const effective = loadEffectiveGSDPreferences()?.preferences;
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      prefs.cmux = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}), enabled: false };
+    });
+    clearCmuxSidebar(effective);
+    ctx.ui.notify("cmux integration disabled in project preferences.", "info");
+    return;
+  }
+
+  const parts = trimmed.split(/\s+/);
+  if (parts.length === 2 && ["notifications", "sidebar", "splits", "browser"].includes(parts[0]) && ["on", "off"].includes(parts[1])) {
+    const feature = parts[0] as "notifications" | "sidebar" | "splits" | "browser";
+    const enabled = parts[1] === "on";
+    if (enabled && !ensureCmuxAvailableForEnable(ctx)) return;
+
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      const next = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}) };
+      next[feature] = enabled;
+      if (enabled) next.enabled = true;
+      prefs.cmux = next;
+    });
+
+    if (!enabled && feature === "sidebar") {
+      clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+    }
+
+    const note = feature === "browser" && enabled
+      ? " Browser surfaces are still a follow-up path."
+      : "";
+    ctx.ui.notify(`cmux ${feature} ${enabled ? "enabled" : "disabled"}.${note}`, "info");
+    return;
+  }
+
+  ctx.ui.notify(
+    "Usage: /gsd cmux <status|on|off|notifications on|notifications off|sidebar on|sidebar off|splits on|splits off|browser on|browser off>",
+    "info",
+  );
+}

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

@@ -740,7 +740,7 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "skill_rules", "custom_instructions", "models", "skill_discovery",
     "skill_staleness_days", "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
-    "notifications", "remote_questions", "git",
+    "notifications", "cmux", "remote_questions", "git",
     "post_unit_hooks", "pre_dispatch_hooks",
     "dynamic_routing", "token_profile", "phases", "parallel",
     "auto_visualize", "auto_report",

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,8 @@ 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";
+import { handleCmux } from "./commands-cmux.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -69,9 +71,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|changelog|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|cmux|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -80,6 +115,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "stop", desc: "Stop auto mode gracefully" },
         { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
         { cmd: "status", desc: "Progress dashboard" },
+        { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
         { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
         { cmd: "queue", desc: "Queue and reorder future milestones" },
         { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
@@ -89,6 +125,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { 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" },
@@ -112,6 +149,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
         { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
         { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
+        { cmd: "cmux", desc: "Manage cmux integration (status, sidebar, notifications, splits)" },
         { cmd: "park", desc: "Park a milestone — skip without deleting" },
         { cmd: "unpark", desc: "Reactivate a parked milestone" },
         { cmd: "update", desc: "Update GSD to the latest version" },
@@ -168,6 +206,38 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((s) => ({ value: `parallel ${s.cmd}`, label: s.cmd, description: s.desc }));
       }
 
+      if (parts[0] === "cmux") {
+        if (parts.length <= 2) {
+          const subPrefix = parts[1] ?? "";
+          const subs = [
+            { cmd: "status", desc: "Show cmux detection, prefs, and capabilities" },
+            { cmd: "on", desc: "Enable cmux integration" },
+            { cmd: "off", desc: "Disable cmux integration" },
+            { cmd: "notifications", desc: "Toggle cmux desktop notifications" },
+            { cmd: "sidebar", desc: "Toggle cmux sidebar metadata" },
+            { cmd: "splits", desc: "Toggle cmux visual subagent splits" },
+            { cmd: "browser", desc: "Toggle future browser integration flag" },
+          ];
+          return subs
+            .filter((s) => s.cmd.startsWith(subPrefix))
+            .map((s) => ({ value: `cmux ${s.cmd}`, label: s.cmd, description: s.desc }));
+        }
+
+        if (parts.length <= 3 && ["notifications", "sidebar", "splits", "browser"].includes(parts[1])) {
+          const togglePrefix = parts[2] ?? "";
+          return [
+            { cmd: "on", desc: "Enable this cmux area" },
+            { cmd: "off", desc: "Disable this cmux area" },
+          ]
+            .filter((item) => item.cmd.startsWith(togglePrefix))
+            .map((item) => ({
+              value: `cmux ${parts[1]} ${item.cmd}`,
+              label: item.cmd,
+              description: item.desc,
+            }));
+        }
+      }
+
       if (parts[0] === "setup" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
         const subs = [
@@ -439,6 +509,18 @@ export async function handleGSDCommand(
     return;
   }
 
+  if (trimmed === "widget" || trimmed.startsWith("widget ")) {
+    const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await import("./auto-dashboard.js");
+    const arg = trimmed.replace(/^widget\s*/, "").trim();
+    if (arg === "full" || arg === "small" || arg === "min" || arg === "off") {
+      setWidgetMode(arg);
+    } else {
+      cycleWidgetMode();
+    }
+    ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
+    return;
+  }
+
   if (trimmed === "visualize") {
     await handleVisualize(ctx);
     return;
@@ -458,6 +540,11 @@ export async function handleGSDCommand(
     return;
   }
 
+  if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
+    await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
+    return;
+  }
+
       if (trimmed === "init") {
         const { detectProjectState } = await import("./detection.js");
         const { showProjectInit, handleReinit } = await import("./init-wizard.js");
@@ -511,6 +598,7 @@ export async function handleGSDCommand(
           await handleDryRun(ctx, projectRoot());
           return;
         }
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
@@ -566,6 +654,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;
@@ -899,7 +993,7 @@ Examples:
       }
 
       if (trimmed === "") {
-        // Bare /gsd defaults to step mode
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }
@@ -954,6 +1048,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
     "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
     "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
+    "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
     "  /gsd config         Set API keys for external tools",
     "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
     "  /gsd hooks          Show post-unit hook configuration",

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

@@ -173,6 +173,13 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`.
   - `on_attention`: boolean — notify when manual attention is needed. Default: `true`.
 
+- `cmux`: configures cmux terminal integration when GSD is running inside a cmux workspace. Keys:
+  - `enabled`: boolean — master toggle for cmux integration. Default: `false`.
+  - `notifications`: boolean — route desktop notifications through cmux. Default: `true` when enabled.
+  - `sidebar`: boolean — publish status, progress, and log metadata to the cmux sidebar. Default: `true` when enabled.
+  - `splits`: boolean — run supported subagent work in visible cmux splits. Default: `false`.
+  - `browser`: boolean — reserve the future browser integration flag. Default: `false`.
+
 - `dynamic_routing`: configures the dynamic model router that adjusts model selection based on task complexity. Keys:
   - `enabled`: boolean — enable dynamic routing. Default: `false`.
   - `tier_models`: object — model overrides per complexity tier. Keys: `light`, `standard`, `heavy`. Values are model ID strings.
@@ -477,6 +484,24 @@ Disables per-unit completion notifications (noisy in long runs) while keeping er
 
 ---
 
+## cmux Example
+
+```yaml
+---
+version: 1
+cmux:
+  enabled: true
+  notifications: true
+  sidebar: true
+  splits: true
+  browser: false
+---
+```
+
+Enables cmux-aware notifications, sidebar metadata, and visible subagent splits when GSD is running inside a cmux terminal.
+
+---
+
 ## Post-Unit Hooks Example
 
 ```yaml

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

@@ -590,7 +590,8 @@ export async function loadFile(path: string): Promise<string | null> {
   try {
     return await fs.readFile(path, 'utf-8');
   } catch (err: unknown) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'EISDIR') return null;
     throw err;
   }
 }
@@ -804,7 +805,7 @@ export async function inlinePriorMilestoneSummary(mid: string, base: string): Pr
  * file not on disk) - callers can distinguish "no manifest" from "empty manifest".
  */
 export async function getManifestStatus(
-  base: string, milestoneId: string,
+  base: string, milestoneId: string, projectRoot?: string,
 ): Promise<ManifestStatus | null> {
   const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
   if (!resolvedPath) return null;
@@ -814,9 +815,18 @@ export async function getManifestStatus(
 
   const manifest = parseSecretsManifest(content);
   const keys = manifest.entries.map(e => e.key);
+
+  // Check both the base path .env AND the project root .env (#1387).
+  // In worktree mode, base is the worktree path which may not have .env.
+  // The project root's .env is where the user actually defined their keys.
   const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
   const existingSet = new Set(existingKeys);
 
+  if (projectRoot && projectRoot !== base) {
+    const rootKeys = await checkExistingEnvKeys(keys, resolve(projectRoot, '.env'));
+    for (const k of rootKeys) existingSet.add(k);
+  }
+
   const result: ManifestStatus = {
     pending: [],
     collected: [],

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

@@ -7,8 +7,8 @@
  */
 
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { nativeRmCached } from "./native-git-bridge.js";
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { nativeRmCached, nativeLsFiles } from "./native-git-bridge.js";
 import { gsdRoot } from "./paths.js";
 
 /**
@@ -79,12 +79,47 @@ const BASELINE_PATTERNS = [
 ];
 
 /**
- * Ensure basePath/.gitignore contains a blanket `.gsd/` ignore.
- * Creates the file if missing; appends `.gsd/` if not present.
+ * Check whether `.gsd/` contains files tracked by git.
+ * If so, the project intentionally keeps `.gsd/` in version control
+ * and we must NOT add `.gsd` to `.gitignore` or attempt migration.
+ *
+ * Returns true if git tracks at least one file under `.gsd/`.
+ * Returns false (safe to ignore) if:
+ *   - Not a git repo
+ *   - `.gsd/` is a symlink (external state, should be ignored)
+ *   - `.gsd/` doesn't exist
+ *   - No tracked files found under `.gsd/`
+ */
+export function hasGitTrackedGsdFiles(basePath: string): boolean {
+  const localGsd = join(basePath, ".gsd");
+
+  // If .gsd doesn't exist or is already a symlink, no tracked files concern
+  if (!existsSync(localGsd)) return false;
+  try {
+    if (lstatSync(localGsd).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+
+  // Check if git tracks any files under .gsd/
+  try {
+    const tracked = nativeLsFiles(basePath, ".gsd");
+    return tracked.length > 0;
+  } catch {
+    // Not a git repo or git not available — safe to proceed
+    return false;
+  }
+}
+
+/**
+ * Ensure basePath/.gitignore contains baseline ignore patterns.
+ * Creates the file if missing; appends missing patterns.
  * Returns true if the file was created or modified, false if already complete.
  *
- * `.gsd/` state is managed externally (symlinked to `~/.gsd/projects/<hash>/`),
- * so the entire directory is always gitignored.
+ * **Safety check:** If `.gsd/` contains git-tracked files (i.e., the project
+ * intentionally keeps `.gsd/` in version control), the `.gsd` ignore pattern
+ * is excluded to prevent data loss. Only the `.gsd` pattern is affected —
+ * all other baseline patterns are still applied normally.
  */
 export function ensureGitignore(
   basePath: string,
@@ -108,8 +143,15 @@ export function ensureGitignore(
       .filter((l) => l && !l.startsWith("#")),
   );
 
+  // Determine which patterns to apply. If .gsd/ has tracked files,
+  // exclude the ".gsd" pattern to prevent deleting tracked state.
+  const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
+  const patternsToApply = gsdIsTracked
+    ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+    : BASELINE_PATTERNS;
+
   // Find patterns not yet present
-  const missing = BASELINE_PATTERNS.filter((p) => !existingLines.has(p));
+  const missing = patternsToApply.filter((p) => !existingLines.has(p));
 
   if (missing.length === 0) return false;
 
@@ -135,6 +177,11 @@ export function ensureGitignore(
  * already in the index even after .gitignore is updated.
  *
  * Only removes from the index (`--cached`), never from disk. Idempotent.
+ *
+ * Note: These are strictly runtime/ephemeral paths (activity logs, lock files,
+ * metrics, STATE.md). They are always safe to untrack, even when the project
+ * intentionally keeps other `.gsd/` files (like PROJECT.md, milestones/) in
+ * version control.
  */
 export function untrackRuntimeFiles(basePath: string): void {
   const runtimePaths = GSD_RUNTIME_PATTERNS;