🤖 Fix system message to conditionally describe workspace type

ammar-agent · ammar-agent · commit acaebbff59f3 · 2025-10-27T01:40:59.000Z
System message incorrectly stated all workspaces are git worktrees.
With SSHRuntime, workspaces can be either worktrees (LocalRuntime) or
regular git clones (SSHRuntime).

Changes:
- buildEnvironmentContext() now uses runtime type to determine message
  - LocalRuntime: 'git worktree' with worktree-specific warnings
  - SSHRuntime: 'git repository' without worktree warnings
- Uses runtime instanceof LocalRuntime (cleaner than git detection)
- Added test to verify different messages for different runtimes

Worktree Reference Audit:
- Updated 30+ user-facing references from 'worktree' to 'workspace'
- Fixed documentation (workspaces.md, intro.md, fork.md, etc.)
- Updated UI components (NewWorkspaceModal, ForceDeleteModal)
- Fixed comments in types, config, and service files
- Kept 170+ accurate references (git commands, LocalRuntime specifics)

The codebase now correctly distinguishes:
- 'Workspace' (generic isolated environment)
- 'Git worktree' (LocalRuntime-specific implementation)
- 'Git clone' (SSHRuntime-specific implementation)
diff --git a/src/services/systemMessage.test.ts b/src/services/systemMessage.test.ts
@@ -10,21 +10,28 @@ import { SSHRuntime } from "@/runtime/SSHRuntime";
 
 describe("buildSystemMessage", () => {
   let tempDir: string;
+  let projectDir: string;
   let workspaceDir: string;
   let globalDir: string;
   let mockHomedir: Mock<typeof os.homedir>;
+  let runtime: LocalRuntime;
 
   beforeEach(async () => {
     // Create temp directory for test
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "systemMessage-test-"));
+    projectDir = path.join(tempDir, "project");
     workspaceDir = path.join(tempDir, "workspace");
     globalDir = path.join(tempDir, ".cmux");
+    await fs.mkdir(projectDir, { recursive: true });
     await fs.mkdir(workspaceDir, { recursive: true });
     await fs.mkdir(globalDir, { recursive: true });
 
     // Mock homedir to return our test directory (getSystemDirectory will append .cmux)
     mockHomedir = spyOn(os, "homedir");
     mockHomedir.mockReturnValue(tempDir);
+
+    // Create a local runtime for tests
+    runtime = new LocalRuntime(tempDir);
   });
 
   afterEach(async () => {
@@ -35,9 +42,9 @@ describe("buildSystemMessage", () => {
   });
 
   test("includes mode-specific section when mode is provided", async () => {
-    // Write instruction file with mode section
+    // Write instruction file with mode section to projectDir
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `# General Instructions
 Always be helpful.
 
@@ -51,10 +58,9 @@ Use diagrams where appropriate.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
-    const runtime = new LocalRuntime(tempDir);
     const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include the mode-specific content
@@ -68,9 +74,9 @@ Use diagrams where appropriate.
   });
 
   test("excludes mode-specific section when mode is not provided", async () => {
-    // Write instruction file with mode section
+    // Write instruction file with mode section to projectDir
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `# General Instructions
 Always be helpful.
 
@@ -83,10 +89,9 @@ Focus on planning and design.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
-    const runtime = new LocalRuntime(tempDir);
     const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir);
 
     // Should NOT include the <plan> mode-specific tag
@@ -98,7 +103,7 @@ Focus on planning and design.
     expect(systemMessage).toContain("Focus on planning and design");
   });
 
-  test("prefers workspace mode section over global mode section", async () => {
+  test("prefers project mode section over global mode section", async () => {
     // Write global instruction file with mode section
     await fs.writeFile(
       path.join(globalDir, "AGENTS.md"),
@@ -109,34 +114,33 @@ Global plan instructions.
 `
     );
 
-    // Write workspace instruction file with mode section
+    // Write project instruction file with mode section
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
-      `# Workspace Instructions
+      path.join(projectDir, "AGENTS.md"),
+      `# Project Instructions
 
 ## Mode: Plan
-Workspace plan instructions (should win).
+Project plan instructions (should win).
 `
     );
 
     const metadata: WorkspaceMetadata = {
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
-    const runtime = new LocalRuntime(tempDir);
     const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
-    // Should include workspace mode section in the <plan> tag (workspace wins)
-    expect(systemMessage).toMatch(/<plan>\s*Workspace plan instructions \(should win\)\./s);
+    // Should include project mode section in the <plan> tag (project wins)
+    expect(systemMessage).toMatch(/<plan>\s*Project plan instructions \(should win\)\./s);
     // Global instructions are still present in <custom-instructions> section (that's correct)
-    // But the mode-specific <plan> section should only have workspace content
+    // But the mode-specific <plan> section should only have project content
     expect(systemMessage).not.toMatch(/<plan>[^<]*Global plan instructions/s);
   });
 
-  test("falls back to global mode section when workspace has none", async () => {
+  test("falls back to global mode section when project has none", async () => {
     // Write global instruction file with mode section
     await fs.writeFile(
       path.join(globalDir, "AGENTS.md"),
@@ -147,22 +151,21 @@ Global plan instructions.
 `
     );
 
-    // Write workspace instruction file WITHOUT mode section
+    // Write project instruction file WITHOUT mode section
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
-      `# Workspace Instructions
-Just general workspace stuff.
+      path.join(projectDir, "AGENTS.md"),
+      `# Project Instructions
+Just general project stuff.
 `
     );
 
     const metadata: WorkspaceMetadata = {
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
-    const runtime = new LocalRuntime(tempDir);
     const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include global mode section as fallback
@@ -171,7 +174,7 @@ Just general workspace stuff.
 
   test("handles mode with special characters by sanitizing tag name", async () => {
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `## Mode: My-Special_Mode!
 Special mode instructions.
 `
@@ -181,10 +184,9 @@ Special mode instructions.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
-    const runtime = new LocalRuntime(tempDir);
     const systemMessage = await buildSystemMessage(
       metadata,
       runtime,
@@ -197,30 +199,30 @@ Special mode instructions.
     expect(systemMessage).toContain("Special mode instructions");
     expect(systemMessage).toContain("</my-special_mode->");
   });
+});
 
-  test("environment context differs between LocalRuntime and SSHRuntime", async () => {
-    const metadata: WorkspaceMetadata = {
-      id: "test-workspace",
-      name: "test-workspace",
-      projectName: "test-project",
-      projectPath: tempDir,
-    };
-
-    // Test with LocalRuntime
-    const localRuntime = new LocalRuntime(tempDir);
-    const localMessage = await buildSystemMessage(metadata, localRuntime, workspaceDir);
-
-    // Should mention "git worktree" and include worktree-specific warnings
-    expect(localMessage).toContain("git worktree");
-    expect(localMessage).toContain("Do not modify or visit other worktrees");
-
-    // Test with SSHRuntime
-    const sshRuntime = new SSHRuntime({ host: "test-host", srcBaseDir: "/remote/path" });
-    const sshMessage = await buildSystemMessage(metadata, sshRuntime, workspaceDir);
-
-    // Should mention "git repository" but not "worktree"
-    expect(sshMessage).toContain("git repository");
-    expect(sshMessage).not.toContain("git worktree");
-    expect(sshMessage).not.toContain("Do not modify or visit other worktrees");
-  });
+test("environment context differs between LocalRuntime and SSHRuntime", async () => {
+  const metadata: WorkspaceMetadata = {
+    id: "test-workspace",
+    name: "test-workspace",
+    projectName: "test-project",
+    projectPath: tempDir,
+  };
+
+  // Test with LocalRuntime
+  const localRuntime = new LocalRuntime(tempDir);
+  const localMessage = await buildSystemMessage(metadata, localRuntime, workspaceDir);
+
+  // Should mention "git worktree" and include worktree-specific warnings
+  expect(localMessage).toContain("git worktree");
+  expect(localMessage).toContain("Do not modify or visit other worktrees");
+
+  // Test with SSHRuntime
+  const sshRuntime = new SSHRuntime({ host: "test-host", srcBaseDir: "/remote/path" });
+  const sshMessage = await buildSystemMessage(metadata, sshRuntime, workspaceDir);
+
+  // Should mention "git repository" but not "worktree"
+  expect(sshMessage).toContain("git repository");
+  expect(sshMessage).not.toContain("git worktree");
+  expect(sshMessage).not.toContain("Do not modify or visit other worktrees");
 });
diff --git a/src/services/systemMessage.ts b/src/services/systemMessage.ts
@@ -1,7 +1,7 @@
 import * as os from "os";
 import * as path from "path";
 import type { WorkspaceMetadata } from "@/types/workspace";
-import { gatherInstructionSets, readInstructionSet } from "@/utils/main/instructionFiles";
+import { readInstructionSet, readInstructionSetFromRuntime } from "@/utils/main/instructionFiles";
 import { extractModeSection } from "@/utils/main/markdown";
 import type { Runtime } from "@/runtime/Runtime";
 import { LocalRuntime } from "@/runtime/LocalRuntime";
@@ -30,6 +30,9 @@ Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for
 </prelude>
 `;
 
+/**
+ * Build environment context XML block describing the workspace.
+ */
 function buildEnvironmentContext(runtime: Runtime, workspacePath: string): string {
   const isWorktree = runtime instanceof LocalRuntime;
 
@@ -58,39 +61,30 @@ You are in a git repository at ${workspacePath}
 }
 
 /**
- * The system directory where global cmux configuration lives.
- * This is where users can place global AGENTS.md and .cmux/PLAN.md files
- * that apply to all workspaces.
+ * Get the system directory where global cmux configuration lives.
+ * Users can place global AGENTS.md and .cmux/PLAN.md files here.
  */
 function getSystemDirectory(): string {
   return path.join(os.homedir(), ".cmux");
 }
 
 /**
- * Builds a system message for the AI model by combining multiple instruction sources.
- *
- * Instruction sources are layered in this order:
- * 1. Global instructions: ~/.cmux/AGENTS.md (+ AGENTS.local.md)
- * 2. Workspace instructions: <workspace>/AGENTS.md (+ AGENTS.local.md)
- * 3. Mode-specific context (if mode provided): Extract a section titled "Mode: <mode>"
- *    (case-insensitive) from the instruction file. We search at most one section in
- *    precedence order: workspace instructions first, then global instructions.
+ * Builds a system message for the AI model by combining instruction sources.
  *
- * Each instruction file location is searched for in priority order:
- * - AGENTS.md
- * - AGENT.md
- * - CLAUDE.md
+ * Instruction layers:
+ * 1. Global: ~/.cmux/AGENTS.md (always included)
+ * 2. Context: workspace/AGENTS.md OR project/AGENTS.md (workspace takes precedence)
+ * 3. Mode: Extracts "Mode: <mode>" section from context then global (if mode provided)
  *
- * If a base instruction file is found, its corresponding .local.md variant is also
- * checked and appended when building the instruction set (useful for personal preferences not committed to git).
+ * File search order: AGENTS.md → AGENT.md → CLAUDE.md
+ * Local variants: AGENTS.local.md appended if found (for .gitignored personal preferences)
  *
- * @param metadata - Workspace metadata
- * @param runtime - Runtime instance (used to determine workspace type)
- * @param workspacePath - Absolute path to the workspace directory
- * @param mode - Optional mode name (e.g., "plan", "exec") - looks for {MODE}.md files if provided
- * @param additionalSystemInstructions - Optional additional system instructions to append at the end
- * @returns System message string with all instruction sources combined
- * @throws Error if metadata is invalid
+ * @param metadata - Workspace metadata (contains projectPath)
+ * @param runtime - Runtime for reading workspace files (supports SSH)
+ * @param workspacePath - Workspace directory path
+ * @param mode - Optional mode name (e.g., "plan", "exec")
+ * @param additionalSystemInstructions - Optional instructions appended last
+ * @throws Error if metadata or workspacePath invalid
  */
 export async function buildSystemMessage(
   metadata: WorkspaceMetadata,
@@ -99,56 +93,39 @@ export async function buildSystemMessage(
   mode?: string,
   additionalSystemInstructions?: string
 ): Promise<string> {
-  // Validate inputs
-  if (!metadata) {
-    throw new Error("Invalid workspace metadata: metadata is required");
-  }
-  if (!workspacePath) {
-    throw new Error("Invalid workspace path: workspacePath is required");
-  }
+  if (!metadata) throw new Error("Invalid workspace metadata: metadata is required");
+  if (!workspacePath) throw new Error("Invalid workspace path: workspacePath is required");
 
-  const systemDir = getSystemDirectory();
-  const workspaceDir = workspacePath;
+  // Read instruction sets
+  const globalInstructions = await readInstructionSet(getSystemDirectory());
+  const workspaceInstructions = await readInstructionSetFromRuntime(runtime, workspacePath);
+  const contextInstructions =
+    workspaceInstructions ?? (await readInstructionSet(metadata.projectPath));
 
-  // Gather instruction sets from both global and workspace directories
-  // Global instructions apply first, then workspace-specific ones
-  const instructionDirectories = [systemDir, workspaceDir];
-  const instructionSegments = await gatherInstructionSets(instructionDirectories);
-  const customInstructions = instructionSegments.join("\n\n");
+  // Combine: global + context (workspace takes precedence over project)
+  const customInstructions = [globalInstructions, contextInstructions].filter(Boolean).join("\n\n");
 
-  // Look for a "Mode: <mode>" section inside instruction sets, preferring workspace over global
-  // This behavior is documented in docs/instruction-files.md - keep both in sync when changing.
+  // Extract mode-specific section (context first, then global fallback)
   let modeContent: string | null = null;
   if (mode) {
-    const workspaceInstructions = await readInstructionSet(workspaceDir);
-    if (workspaceInstructions) {
-      modeContent = extractModeSection(workspaceInstructions, mode);
-    }
-    if (!modeContent) {
-      const globalInstructions = await readInstructionSet(systemDir);
-      if (globalInstructions) {
-        modeContent = extractModeSection(globalInstructions, mode);
-      }
-    }
+    modeContent =
+      (contextInstructions && extractModeSection(contextInstructions, mode)) ??
+      (globalInstructions && extractModeSection(globalInstructions, mode)) ??
+      null;
   }
 
-  // Build the final system message
-  const environmentContext = buildEnvironmentContext(runtime, workspaceDir);
-  const trimmedPrelude = PRELUDE.trim();
-  let systemMessage = `${trimmedPrelude}\n\n${environmentContext}`;
+  // Build system message
+  let systemMessage = `${PRELUDE.trim()}\n\n${buildEnvironmentContext(runtime, workspacePath)}`;
 
-  // Add custom instructions if found
   if (customInstructions) {
     systemMessage += `\n<custom-instructions>\n${customInstructions}\n</custom-instructions>`;
   }
 
-  // Add mode-specific content if found
   if (modeContent) {
     const tag = (mode ?? "mode").toLowerCase().replace(/[^a-z0-9_-]/gi, "-");
     systemMessage += `\n\n<${tag}>\n${modeContent}\n</${tag}>`;
   }
 
-  // Add additional system instructions at the end (highest priority)
   if (additionalSystemInstructions) {
     systemMessage += `\n\n<additional-instructions>\n${additionalSystemInstructions}\n</additional-instructions>`;
   }
