gsd-pi 2.36.0 → 2.37.0-dev.68605cd

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

@@ -15,7 +15,7 @@ import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
 import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote, checkRemoteAutoSession } from "./auto.js";
 import { dispatchDirectPhase } from "./auto-direct-dispatch.js";
 import { resolveProjectRoot } from "./worktree.js";
 import { assertSafeDirectory } from "./validate-directory.js";
@@ -49,6 +49,8 @@ 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";
+import { showNextAction } from "../shared/mod.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -71,41 +73,93 @@ export function projectRoot(): string {
 }
 
 /**
- * Check if another process holds the auto-mode session lock.
- * Returns the lock data if a remote session is alive, null otherwise.
+ * Guard against starting auto-mode when a remote session is already running.
+ * Returns true if the caller should proceed with startAuto, false if handled.
  */
-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 };
-}
+async function guardRemoteSession(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  // Local session already active — proceed (startAuto handles re-entrant calls)
+  if (isAutoActive() || isAutoPaused()) return true;
+
+  const remote = checkRemoteAutoSession(projectRoot());
+  if (!remote.running || !remote.pid) return true;
+
+  const unitLabel = remote.unitType && remote.unitId
+    ? `${remote.unitType} (${remote.unitId})`
+    : "unknown unit";
+  const unitsMsg = remote.completedUnits != null
+    ? `${remote.completedUnits} units completed`
+    : "";
+
+  const choice = await showNextAction(ctx, {
+    title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
+    summary: [
+      `Currently executing: ${unitLabel}`,
+      ...(unitsMsg ? [unitsMsg] : []),
+      ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
+    ],
+    actions: [
+      {
+        id: "status",
+        label: "View status",
+        description: "Show the current GSD progress dashboard.",
+        recommended: true,
+      },
+      {
+        id: "steer",
+        label: "Steer the session",
+        description: "Use /gsd steer <instruction> to redirect the running session.",
+      },
+      {
+        id: "stop",
+        label: "Stop remote session",
+        description: `Send SIGTERM to PID ${remote.pid} to stop it gracefully.`,
+      },
+      {
+        id: "force",
+        label: "Force start (steal lock)",
+        description: "Start a new session, terminating the existing one.",
+      },
+    ],
+    notYetMessage: "Run /gsd when ready.",
+  });
 
-/**
- * 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;
+  if (choice === "status") {
+    await handleStatus(ctx);
+    return false;
+  }
+  if (choice === "steer") {
+    ctx.ui.notify(
+      "Use /gsd steer <instruction> to redirect the running auto-mode session.\n" +
+      "Example: /gsd steer Use Postgres instead of SQLite",
+      "info",
+    );
+    return false;
+  }
+  if (choice === "stop") {
+    const result = stopAutoRemote(projectRoot());
+    if (result.found) {
+      ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+    } else if (result.error) {
+      ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+    } else {
+      ctx.ui.notify("Remote session is no longer running.", "info");
+    }
+    return false;
+  }
+  if (choice === "force") {
+    return true; // Proceed — startAuto will steal the lock
+  }
+
+  // "not_yet" or escape
+  return false;
 }
 
 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" },
@@ -114,6 +168,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" },
@@ -147,6 +202,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" },
@@ -203,6 +259,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 = [
@@ -474,6 +562,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;
@@ -493,6 +593,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");
@@ -546,10 +651,10 @@ 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());
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
         return;
       }
@@ -558,6 +663,7 @@ export async function handleGSDCommand(
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), verboseMode);
         return;
       }
@@ -941,7 +1047,7 @@ Examples:
       }
 
       if (trimmed === "") {
-        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
+        if (!(await guardRemoteSession(ctx, pi))) return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }
@@ -996,6 +1102,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/git-service.ts

@@ -479,9 +479,20 @@ export class GitServiceImpl {
 
     const wtName = detectWorktreeName(this.basePath);
     if (wtName) {
+      // Auto-mode worktrees use milestone/<MID> branches (wtName = milestone ID)
+      const milestoneBranch = `milestone/${wtName}`;
+      const currentBranch = nativeGetCurrentBranch(this.basePath);
+
+      // If we're on a milestone/<MID> branch, use it (auto-mode case)
+      if (currentBranch.startsWith("milestone/")) {
+        return currentBranch;
+      }
+
+      // Otherwise check for manual worktree branch (worktree/<name>)
       const wtBranch = `worktree/${wtName}`;
       if (nativeBranchExists(this.basePath, wtBranch)) return wtBranch;
-      return nativeGetCurrentBranch(this.basePath);
+
+      return currentBranch;
     }
 
     // Repo-level default detection: origin/HEAD → main → master → current branch.

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

@@ -2,7 +2,8 @@
 // Human-readable display of past auto-mode unit executions.
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { formatDuration, padRight, truncateWithEllipsis } from "../shared/format-utils.js";
+import { formatDuration, truncateWithEllipsis } from "../shared/format-utils.js";
+import { padRight } from "../shared/layout-utils.js";
 import {
   getLedger, getProjectTotals, formatCost, formatTokenCount,
   aggregateBySlice, aggregateByPhase, aggregateByModel, loadLedgerFromDisk,

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

@@ -65,6 +65,7 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
+import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js";
 
 // ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
 // agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
@@ -623,6 +624,13 @@ export default function (pi: ExtensionAPI) {
     const stopContextTimer = debugTime("context-inject");
     const systemContent = loadPrompt("system");
     const loadedPreferences = loadEffectiveGSDPreferences();
+    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+      markCmuxPromptShown();
+      ctx.ui.notify(
+        "cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.",
+        "info",
+      );
+    }
     let preferenceBlock = "";
     if (loadedPreferences) {
       const cwd = process.cwd();

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

@@ -20,8 +20,10 @@ import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 
-// Re-export from shared — canonical implementation lives in format-utils.
-export { formatTokenCount } from "../shared/mod.js";
+// Re-export from shared — import directly from format-utils to avoid pulling
+// in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
+// outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
+export { formatTokenCount } from "../shared/format-utils.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 

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

@@ -4,6 +4,7 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -23,7 +24,15 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
 ): void {
-  if (!shouldSendDesktopNotification(kind)) return;
+  const loaded = loadEffectiveGSDPreferences()?.preferences;
+  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+
+  const cmux = resolveCmuxConfig(loaded);
+  if (cmux.notifications) {
+    const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+    if (delivered) return;
+    emitOsc777Notification(title, message);
+  }
 
   try {
     const command = buildDesktopNotificationCommand(process.platform, title, message, level);

package/src/resources/extensions/gsd/preferences-types.ts

@@ -68,6 +68,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "budget_enforcement",
   "context_pause_threshold",
   "notifications",
+  "cmux",
   "remote_questions",
   "git",
   "post_unit_hooks",
@@ -84,6 +85,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "search_provider",
   "compression_strategy",
   "context_selection",
+  "widget_mode",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -164,6 +166,14 @@ export interface RemoteQuestionsConfig {
   poll_interval_seconds?: number;  // clamped to 2-30
 }
 
+export interface CmuxPreferences {
+  enabled?: boolean;
+  notifications?: boolean;
+  sidebar?: boolean;
+  splits?: boolean;
+  browser?: boolean;
+}
+
 export interface GSDPreferences {
   version?: number;
   mode?: WorkflowMode;
@@ -182,6 +192,7 @@ export interface GSDPreferences {
   budget_enforcement?: BudgetEnforcementMode;
   context_pause_threshold?: number;
   notifications?: NotificationPreferences;
+  cmux?: CmuxPreferences;
   remote_questions?: RemoteQuestionsConfig;
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
@@ -202,6 +213,8 @@ export interface GSDPreferences {
   compression_strategy?: CompressionStrategy;
   /** Context selection mode for file inlining. "full" inlines entire files, "smart" uses semantic chunking. Default derived from token profile. */
   context_selection?: ContextSelectionMode;
+  /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
+  widget_mode?: "full" | "small" | "min" | "off";
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -242,6 +242,32 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Cmux ───────────────────────────────────────────────────────────────
+  if (preferences.cmux !== undefined) {
+    if (preferences.cmux && typeof preferences.cmux === "object") {
+      const cmux = preferences.cmux as Record<string, unknown>;
+      const validatedCmux: NonNullable<GSDPreferences["cmux"]> = {};
+      if (cmux.enabled !== undefined) validatedCmux.enabled = !!cmux.enabled;
+      if (cmux.notifications !== undefined) validatedCmux.notifications = !!cmux.notifications;
+      if (cmux.sidebar !== undefined) validatedCmux.sidebar = !!cmux.sidebar;
+      if (cmux.splits !== undefined) validatedCmux.splits = !!cmux.splits;
+      if (cmux.browser !== undefined) validatedCmux.browser = !!cmux.browser;
+
+      const knownCmuxKeys = new Set(["enabled", "notifications", "sidebar", "splits", "browser"]);
+      for (const key of Object.keys(cmux)) {
+        if (!knownCmuxKeys.has(key)) {
+          warnings.push(`unknown cmux key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validatedCmux).length > 0) {
+        validated.cmux = validatedCmux;
+      }
+    } else {
+      errors.push("cmux must be an object");
+    }
+  }
+
   // ─── Remote Questions ───────────────────────────────────────────────
   if (preferences.remote_questions !== undefined) {
     if (preferences.remote_questions && typeof preferences.remote_questions === "object") {

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

@@ -45,6 +45,7 @@ export type {
   SkillDiscoveryMode,
   AutoSupervisorConfig,
   RemoteQuestionsConfig,
+  CmuxPreferences,
   GSDPreferences,
   LoadedGSDPreferences,
   SkillResolution,
@@ -241,6 +242,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     notifications: (base.notifications || override.notifications)
       ? { ...(base.notifications ?? {}), ...(override.notifications ?? {}) }
       : undefined,
+    cmux: (base.cmux || override.cmux)
+      ? { ...(base.cmux ?? {}), ...(override.cmux ?? {}) }
+      : undefined,
     remote_questions: override.remote_questions
       ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
       : base.remote_questions,

package/src/resources/extensions/gsd/prompts/research-milestone.md

@@ -25,9 +25,10 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content
-6. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
-7. Write `{{outputPath}}`
+5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
+6. Use the **Research** output template from the inlined context above — include only sections that have real content
+7. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
+8. Write `{{outputPath}}`
 
 ## Strategic Questions to Answer
 

package/src/resources/extensions/gsd/prompts/research-slice.md

@@ -46,8 +46,9 @@ Research what this slice needs. Narrate key findings and surprises as you go —
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
-6. Write `{{outputPath}}`
+5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
+6. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
+7. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.
 

package/src/resources/extensions/gsd/session-lock.ts

@@ -40,6 +40,19 @@ export type SessionLockResult =
   | { acquired: true }
   | { acquired: false; reason: string; existingPid?: number };
 
+export type SessionLockFailureReason =
+  | "compromised"
+  | "missing-metadata"
+  | "pid-mismatch";
+
+export interface SessionLockStatus {
+  valid: boolean;
+  failureReason?: SessionLockFailureReason;
+  existingPid?: number;
+  expectedPid?: number;
+  recovered?: boolean;
+}
+
 // ─── Module State ───────────────────────────────────────────────────────────
 
 /** Release function from proper-lockfile — calling it releases the OS lock. */
@@ -368,7 +381,7 @@ export function updateSessionLock(
  *
  * This is called periodically during the dispatch loop.
  */
-export function validateSessionLock(basePath: string): boolean {
+export function getSessionLockStatus(basePath: string): SessionLockStatus {
   // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
   if (_lockCompromised) {
     // Recovery gate (#1512): Before declaring the lock lost, check if the lock
@@ -385,18 +398,23 @@ export function validateSessionLock(basePath: string): boolean {
           process.stderr.write(
             `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
           );
-          return true;
+          return { valid: true, recovered: true };
         }
       } catch {
         // Re-acquisition failed — fall through to return false
       }
     }
-    return false;
+    return {
+      valid: false,
+      failureReason: "compromised",
+      existingPid: existing?.pid,
+      expectedPid: process.pid,
+    };
   }
 
   // If we have an OS-level lock, we're still the owner
   if (_releaseFunction && _lockedPath === basePath) {
-    return true;
+    return { valid: true };
   }
 
   // Fallback: check the lock file PID
@@ -404,10 +422,27 @@ export function validateSessionLock(basePath: string): boolean {
   const existing = readExistingLockData(lp);
   if (!existing) {
     // Lock file was deleted — we lost ownership
-    return false;
+    return {
+      valid: false,
+      failureReason: "missing-metadata",
+      expectedPid: process.pid,
+    };
+  }
+
+  if (existing.pid !== process.pid) {
+    return {
+      valid: false,
+      failureReason: "pid-mismatch",
+      existingPid: existing.pid,
+      expectedPid: process.pid,
+    };
   }
 
-  return existing.pid === process.pid;
+  return { valid: true };
+}
+
+export function validateSessionLock(basePath: string): boolean {
+  return getSessionLockStatus(basePath).valid;
 }
 
 /**

package/src/resources/extensions/gsd/templates/preferences.md

@@ -57,6 +57,12 @@ notifications:
   on_budget:
   on_milestone:
   on_attention:
+cmux:
+  enabled:
+  notifications:
+  sidebar:
+  splits:
+  browser:
 remote_questions:
   channel:
   channel_id: