gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -19,7 +19,6 @@ import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-comma
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
-import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
@@ -29,10 +28,30 @@ const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
  * hardcoding absolute paths in the system prompt template. Only skills
  * that actually exist on disk are included in the table. (#3575)
  */
-const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> = [
+export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> = [
   { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
   { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
   { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+  { trigger: "Code review - security, performance, bugs, quality review of staged/unstaged diffs or PRs", skill: "review" },
+  { trigger: "Test generation or execution - auto-detect framework, generate tests, run suite, analyze failures", skill: "test" },
+  { trigger: "Linting/formatting - run the detected linter/formatter with auto-fix, report remaining issues", skill: "lint" },
+  { trigger: "Polishing UI details - animations, hover states, typography, borders, micro-interactions, optical alignment", skill: "make-interfaces-feel-better" },
+  { trigger: "Accessibility audit - WCAG, screen reader, keyboard navigation, a11y review", skill: "accessibility" },
+  { trigger: "Planning interviews - stress-test a plan, grill the user, resolve decision trees one branch at a time", skill: "grill-me" },
+  { trigger: "Interface design - produce 3+ radically different designs for a module/API, compare in prose, synthesize", skill: "design-an-interface" },
+  { trigger: "TDD - red-green-refactor vertical slices, never refactor while red, tests survive refactors", skill: "tdd" },
+  { trigger: "Draft a milestone brief (M###-CONTEXT.md) or PRD from current conversation context", skill: "write-milestone-brief" },
+  { trigger: "Break a plan into vertical-slice roadmap slices (M###-ROADMAP.md) or GitHub issues with dependency ordering", skill: "decompose-into-slices" },
+  { trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" },
+  { trigger: "Block completion claims until verification evidence has been produced in this message", skill: "verify-before-complete" },
+  { trigger: "Create a Model Context Protocol (MCP) server — tool design, error handling, Inspector testing, evals", skill: "create-mcp-server" },
+  { trigger: "Write documentation, proposals, specs, RFCs, or READMEs for a fresh reader", skill: "write-docs" },
+  { trigger: "Post-mortem a failed GSD auto-mode run using .gsd/activity, .gsd/journal, and .gsd/metrics.json", skill: "forensics" },
+  { trigger: "Prepare a clean cross-session handoff — continue.md + summary updates (pause/resume work)", skill: "handoff" },
+  { trigger: "Security review with STRIDE threat modeling and exploit-scenario reporting", skill: "security-review" },
+  { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
+  { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
+  { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
 ];
 
 function buildBundledSkillsTable(): string {
@@ -79,15 +98,20 @@ export async function buildBeforeAgentStartResult(
     shortcutShell: formatShortcut("Ctrl+Alt+B"),
   });
   let loadedPreferences = loadEffectiveGSDPreferences();
-  if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-    markCmuxPromptShown();
-    if (autoEnableCmuxPreferences()) {
-      loadedPreferences = loadEffectiveGSDPreferences();
-      ctx.ui.notify(
-        "cmux detected — auto-enabled. Run /gsd cmux off to disable.",
-        "info",
-      );
+  try {
+    const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+      markCmuxPromptShown();
+      if (autoEnableCmuxPreferences()) {
+        loadedPreferences = loadEffectiveGSDPreferences();
+        ctx.ui.notify(
+          "cmux detected — auto-enabled. Run /gsd cmux off to disable.",
+          "info",
+        );
+      }
     }
+  } catch (e) {
+    logWarning("bootstrap", `cmux prompt setup skipped: ${(e as Error).message}`);
   }
 
   let preferenceBlock = "";
@@ -111,36 +135,21 @@ export async function buildBeforeAgentStartResult(
     );
   }
 
-  let memoryBlock = "";
+  // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+  // and best-effort — first run absorbs the existing decisions table into
+  // the memory store; subsequent runs are a single sentinel SELECT.
   try {
-    const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
-
-    // Always-on "critical" set — small, stable memories that belong in every
-    // turn (gotchas, environment, conventions). Ranked by the existing score.
-    const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention"]);
-    const allRanked = getActiveMemoriesRanked(60);
-    const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, 5);
-    const criticalIds = new Set(critical.map((m) => m.id));
-
-    // Prompt-relevance set — hybrid FTS5 + (future) semantic retrieval.
-    let relevant: typeof allRanked = [];
-    const userPrompt = (event.prompt ?? "").trim();
-    if (userPrompt) {
-      const hits = queryMemoriesRanked({ query: userPrompt, k: 10 });
-      relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
-    }
-
-    const merged = [...critical, ...relevant];
-    if (merged.length > 0) {
-      const formatted = formatMemoriesForPrompt(merged, 2000);
-      if (formatted) {
-        memoryBlock = `\n\n${formatted}`;
-      }
+    const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+    const written = backfillDecisionsToMemories();
+    if (written > 0) {
+      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
     }
   } catch (e) {
-    logWarning("bootstrap", `memory block fetch failed: ${(e as Error).message}`);
+    logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
+  const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
+
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -220,6 +229,64 @@ export async function buildBeforeAgentStartResult(
   };
 }
 
+/**
+ * ADR-013 step 4 — auto-injection parity for the memories table.
+ *
+ * Mirrors loadKnowledgeBlock by producing a labeled, deterministic block
+ * combining two memory sets:
+ *
+ * 1. Always-on "critical" set — top-ranked active memories in categories
+ *    that future GSD turns generally want without asking. After ADR-013
+ *    expands this to include "architecture", these memories serve as the
+ *    auto-injected replacement for inlineDecisionsFromDb when the cutover
+ *    in step 6 lands.
+ * 2. Prompt-relevance set — FTS5/semantic hits against the current user
+ *    prompt, deduplicated against the critical set.
+ *
+ * Both sets are ranked, merged, and rendered via formatMemoriesForPrompt
+ * with a token-budget cap. Failures degrade gracefully — the function never
+ * throws and returns "" so the system prompt construction continues.
+ */
+export async function loadMemoryBlock(userPrompt: string): Promise<string> {
+  try {
+    const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+
+    // Categories that belong in every turn. Pre-ADR-013 this was just
+    // {gotcha, environment, convention}. ADR-013 adds "architecture" so
+    // decision-equivalent memories survive the inlineDecisionsFromDb cutover
+    // in step 6.
+    const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention", "architecture"]);
+    const CRITICAL_CAP = 8;
+    const QUERY_K = 10;
+    // ~1 token ≈ 4 chars. 4000 chars ≈ 1000 tokens — comfortably under the
+    // KNOWLEDGE.md 4KB warning threshold and roughly twice the pre-ADR-013
+    // budget so the absorbed DECISIONS surface fits.
+    const CHAR_BUDGET = 4000;
+
+    const allRanked = getActiveMemoriesRanked(80);
+    const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, CRITICAL_CAP);
+    const criticalIds = new Set(critical.map((m) => m.id));
+
+    let relevant: typeof allRanked = [];
+    const trimmed = userPrompt.trim();
+    if (trimmed) {
+      const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
+      relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+    }
+
+    const merged = [...critical, ...relevant];
+    if (merged.length === 0) return "";
+
+    const formatted = formatMemoriesForPrompt(merged, CHAR_BUDGET);
+    if (!formatted) return "";
+
+    return `\n\n[MEMORY — Critical and prompt-relevant memories from the GSD memory store]\n\n${formatted}`;
+  } catch (e) {
+    logWarning("bootstrap", `memory block fetch failed: ${(e as Error).message}`);
+    return "";
+  }
+}
+
 export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: string; globalSizeKb: number } {
   // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
   let globalKnowledge = "";

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -28,8 +28,29 @@ const QUEUE_SAFE_TOOLS = new Set([
 /**
  * Bash commands that are read-only / investigative — safe during queue mode.
  * Matches the leading command in a bash invocation.
+ *
+ * Extension policy: add commands here when they are read-only / diagnostic.
+ * Never add commands that mutate project state (write files, run builds that
+ * emit artifacts, install packages, etc.).
+ *
+ * Current read-only additions (Bug #4385):
+ *   npm run <diagnostic> — read-only diagnostic scripts: test, lint, typecheck, etc.
+ *                         NOT: build, install, compile, generate, deploy (artifact-producing)
+ *   npm ls/list/info    — inspect installed packages (read-only)
+ *   npm outdated/audit  — security/update checks (read-only)
+ *   npx <pkg>           — run a package binary without installing globally
+ *   tsx                 — TypeScript runner used for dry-run / inspection scripts
+ *   node --print        — evaluate and print an expression, no side effects
+ *   python / python3    — script inspection, version checks
+ *   pip / pip3 show     — show installed package info (read-only)
+ *   jq                  — read-only JSON query
+ *   yq                  — read-only YAML query
+ *   curl -s / curl --silent — fetch for inspection (no -o / no output redirect)
+ *   openssl version     — version / certificate inspection
+ *   env / printenv      — print environment variables
+ *   true / false        — shell no-ops / test exit codes
  */
-const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s)/;
+const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
 
 const verifiedDepthMilestones = new Set<string>();
 let activeQueuePhase = false;
@@ -117,9 +138,21 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   };
 }
 
+const EMPTY_SNAPSHOT: WriteGateSnapshot = {
+  verifiedDepthMilestones: [],
+  activeQueuePhase: false,
+  pendingGateId: null,
+};
+
 export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
-  if (!existsSync(path)) return currentWriteGateSnapshot();
+  if (!existsSync(path)) {
+    // When persist mode is active and the file has been deleted, treat it as a
+    // full state reset so deleting the file clears the HARD BLOCK gate.
+    // In non-persist mode the file is never written, so fall back to in-memory.
+    if (shouldPersistWriteGateSnapshot()) return EMPTY_SNAPSHOT;
+    return currentWriteGateSnapshot();
+  }
   try {
     return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
   } catch {

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -0,0 +1,111 @@
+/**
+ * clean-root-preflight.ts — Preflight gate for dirty working trees before milestone merges.
+ *
+ * #2909: Adds a fast-path git status check before milestone completion merges.
+ * When the working tree is dirty the user is warned and changes are auto-stashed
+ * so the merge can proceed cleanly.  After the merge completes, postflightPopStash
+ * restores the stashed changes.
+ *
+ * Design constraints (from Trek-e approval):
+ *  - Warn the user before stashing (no silent surprises)
+ *  - git stash push / git stash pop only — no custom stash management layer
+ *  - Stash/pop errors are logged but MUST NOT block the merge
+ *  - Fast-path status check — clean trees pay no extra cost
+ */
+
+import { execFileSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { logWarning } from "./workflow-logger.js";
+import { nativeHasChanges } from "./native-git-bridge.js";
+
+export interface PreflightResult {
+  /** true when a stash was pushed and postflightPopStash should be called */
+  stashPushed: boolean;
+  /** human-readable summary of what happened (empty string for clean trees) */
+  summary: string;
+}
+
+/**
+ * Check the working tree for dirty files before a milestone merge.
+ *
+ * Clean tree path: O(1) — returns immediately with stashPushed=false.
+ *
+ * Dirty tree path:
+ *  1. Emits a warning notification via the provided `notify` callback.
+ *  2. Runs `git stash push --include-untracked -m "gsd-preflight-stash"`.
+ *  3. Returns stashPushed=true so the caller knows to call postflightPopStash.
+ *
+ * Any stash error is logged but does NOT throw — the merge proceeds regardless.
+ */
+export function preflightCleanRoot(
+  basePath: string,
+  milestoneId: string,
+  notify: (message: string, level: "info" | "warning" | "error") => void,
+): PreflightResult {
+  // Fast-path: clean tree — nothing to do
+  let isDirty = false;
+  try {
+    isDirty = nativeHasChanges(basePath);
+  } catch (err) {
+    // If the status check itself fails, treat as clean and let the merge decide
+    logWarning("preflight", `clean-root status check failed: ${err instanceof Error ? err.message : String(err)}`);
+    return { stashPushed: false, summary: "" };
+  }
+
+  if (!isDirty) {
+    return { stashPushed: false, summary: "" };
+  }
+
+  // Warn the user before stashing
+  const warnMsg = `Working tree has uncommitted changes before milestone ${milestoneId} merge. Auto-stashing to allow clean merge (stash will be restored after merge).`;
+  notify(warnMsg, "warning");
+
+  // Push the stash
+  try {
+    execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    return {
+      stashPushed: true,
+      summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
+    };
+  } catch (err) {
+    // Stash failure is non-fatal — log and let the merge attempt proceed
+    const msg = `git stash push failed before merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}`;
+    logWarning("preflight", msg);
+    notify(`Auto-stash failed before milestone ${milestoneId} merge — proceeding anyway. ${msg}`, "warning");
+    return { stashPushed: false, summary: `stash-push-failed: ${msg}` };
+  }
+}
+
+/**
+ * Restore stashed changes after a milestone merge completes.
+ *
+ * Only called when preflightCleanRoot returned stashPushed=true.
+ * Any pop error (e.g. conflict) is logged and notified but does NOT throw —
+ * the merge already completed successfully.
+ */
+export function postflightPopStash(
+  basePath: string,
+  milestoneId: string,
+  notify: (message: string, level: "info" | "warning" | "error") => void,
+): void {
+  try {
+    execFileSync("git", ["stash", "pop"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    notify(`Restored stashed changes after milestone ${milestoneId} merge.`, "info");
+  } catch (err) {
+    // Pop conflicts mean the merged code collides with the stashed changes.
+    // Log a warning — the user needs to resolve manually, but the merge succeeded.
+    const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+    logWarning("preflight", msg);
+    notify(msg, "warning");
+  }
+}

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

@@ -43,6 +43,25 @@ import {
   validateFetchedContent,
 } from "../../workflow-install.js";
 
+/**
+ * Refuses interactive commands that mutate durable .gsd/ planning state while
+ * auto-mode holds the worktree. Returns true if the command was blocked and
+ * the caller should return immediately; false if it is safe to proceed.
+ *
+ * Auto-mode's squash merge performs a pre-merge dirty-tree check; concurrent
+ * writes by interactive commands between that check and the merge itself
+ * cause __dirty_working_tree__ failures (#4704).
+ */
+function requireNotAutoActive(commandName: string, ctx: ExtensionCommandContext): boolean {
+  if (!isAutoActive()) return false;
+  ctx.ui.notify(
+    `${commandName} cannot run while auto-mode is active.\n` +
+    `Stop auto-mode first with /gsd stop, then run ${commandName}.`,
+    "error",
+  );
+  return true;
+}
+
 // ─── Custom Workflow Subcommands ─────────────────────────────────────────
 
 const RESERVED_SUBCOMMANDS = new Set([
@@ -473,12 +492,14 @@ async function handleCustomWorkflow(
 export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
   // ── /gsd do — natural language routing (must be early to route to other commands) ──
   if (trimmed === "do" || trimmed.startsWith("do ")) {
+    if (requireNotAutoActive("/gsd do", ctx)) return true;
     const { handleDo } = await import("../../commands-do.js");
     await handleDo(trimmed.replace(/^do\s*/, "").trim(), ctx, pi);
     return true;
   }
   // ── Backlog management ──
   if (trimmed === "backlog" || trimmed.startsWith("backlog ")) {
+    if (requireNotAutoActive("/gsd backlog", ctx)) return true;
     const { handleBacklog } = await import("../../commands-backlog.js");
     await handleBacklog(trimmed.replace(/^backlog\s*/, "").trim(), ctx, pi);
     return true;
@@ -490,26 +511,22 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
   }
 
   if (trimmed === "queue") {
+    if (requireNotAutoActive("/gsd queue", ctx)) return true;
     await showQueue(ctx, pi, projectRoot());
     return true;
   }
   if (trimmed === "discuss") {
+    if (requireNotAutoActive("/gsd discuss", ctx)) return true;
     await showDiscuss(ctx, pi, projectRoot());
     return true;
   }
   if (trimmed === "quick" || trimmed.startsWith("quick ")) {
-    if (isAutoActive()) {
-      ctx.ui.notify(
-        "/gsd quick cannot run while auto-mode is active.\n" +
-        "Stop auto-mode first with /gsd stop, then run /gsd quick.",
-        "error",
-      );
-      return true;
-    }
+    if (requireNotAutoActive("/gsd quick", ctx)) return true;
     await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
     return true;
   }
   if (trimmed === "new-milestone") {
+    if (requireNotAutoActive("/gsd new-milestone", ctx)) return true;
     const basePath = projectRoot();
     const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
     if (existsSync(headlessContextPath)) {
@@ -531,6 +548,7 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     return true;
   }
   if (trimmed === "park" || trimmed.startsWith("park ")) {
+    if (requireNotAutoActive("/gsd park", ctx)) return true;
     const basePath = projectRoot();
     const arg = trimmed.replace(/^park\s*/, "").trim();
     let targetId = arg;
@@ -556,6 +574,7 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     return true;
   }
   if (trimmed === "unpark" || trimmed.startsWith("unpark ")) {
+    if (requireNotAutoActive("/gsd unpark", ctx)) return true;
     const basePath = projectRoot();
     const arg = trimmed.replace(/^unpark\s*/, "").trim();
     let targetId = arg;

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

@@ -1,6 +1,5 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { clearCmuxSidebar, CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } from "../cmux/index.js";
 import { saveFile } from "./files.js";
 import {
   getProjectGSDPreferencesPath,
@@ -77,7 +76,9 @@ function resolveProjectPreferencesWritePath(): string {
   return loadProjectGSDPreferences()?.path ?? getProjectGSDPreferencesPath();
 }
 
-function formatCmuxStatus(): string {
+async function formatCmuxStatus(): Promise<string> {
+  const { CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } =
+    await import("../cmux/index.js");
   const loaded = loadEffectiveGSDPreferences();
   const detected = detectCmuxEnvironment();
   const resolved = resolveCmuxConfig(loaded?.preferences);
@@ -103,7 +104,8 @@ function formatCmuxStatus(): string {
   ].join("\n");
 }
 
-function ensureCmuxAvailableForEnable(ctx: ExtensionCommandContext): boolean {
+async function ensureCmuxAvailableForEnable(ctx: ExtensionCommandContext): Promise<boolean> {
+  const { detectCmuxEnvironment } = await import("../cmux/index.js");
   const detected = detectCmuxEnvironment();
   if (detected.available) return true;
   ctx.ui.notify(
@@ -116,12 +118,12 @@ function ensureCmuxAvailableForEnable(ctx: ExtensionCommandContext): boolean {
 export async function handleCmux(args: string, ctx: ExtensionCommandContext): Promise<void> {
   const trimmed = args.trim();
   if (!trimmed || trimmed === "status") {
-    ctx.ui.notify(formatCmuxStatus(), "info");
+    ctx.ui.notify(await formatCmuxStatus(), "info");
     return;
   }
 
   if (trimmed === "on") {
-    if (!ensureCmuxAvailableForEnable(ctx)) return;
+    if (!await ensureCmuxAvailableForEnable(ctx)) return;
     await writeProjectCmuxPreferences(ctx, (prefs) => {
       prefs.cmux = {
         enabled: true,
@@ -142,6 +144,7 @@ export async function handleCmux(args: string, ctx: ExtensionCommandContext): Pr
     await writeProjectCmuxPreferences(ctx, (prefs) => {
       prefs.cmux = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}), enabled: false };
     });
+    const { clearCmuxSidebar } = await import("../cmux/index.js");
     clearCmuxSidebar(effective);
     ctx.ui.notify("cmux integration disabled in project preferences.", "info");
     return;
@@ -151,7 +154,7 @@ export async function handleCmux(args: string, ctx: ExtensionCommandContext): Pr
   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;
+    if (enabled && !await ensureCmuxAvailableForEnable(ctx)) return;
 
     await writeProjectCmuxPreferences(ctx, (prefs) => {
       const next = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}) };
@@ -161,6 +164,7 @@ export async function handleCmux(args: string, ctx: ExtensionCommandContext): Pr
     });
 
     if (!enabled && feature === "sidebar") {
+      const { clearCmuxSidebar } = await import("../cmux/index.js");
       clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
     }