Fix AGENTS.md loading: workspace first, project fallback

Add Runtime abstraction support for reading AGENTS.md from workspaces,
with graceful fallback to project root when workspace file doesn't exist.

Problem:
- SSH workspaces are on remote machines, can't use local fs.readFile()
- AGENTS.md may not be cloned into SSH workspace yet
- Need to support both local worktrees and remote SSH workspaces

Solution:
- Add runtime parameter to buildSystemMessage()
- Read workspace AGENTS.md using Runtime.readFile() (works for SSH)
- Fall back to project root AGENTS.md if workspace doesn't have one
- Preserves branch-specific instructions for local workspaces
- Provides sensible defaults for SSH workspaces during clone

Changes:
- buildSystemMessage() now accepts Runtime parameter
- New readInstructionSetFromRuntime() uses runtime to read workspace files
- Instruction priority: global → workspace (if exists) → project (fallback)
- Mode section priority: workspace → project → global
- Updated docs/instruction-files.md to reflect fallback behavior
- Updated all tests to pass runtime parameter
- Updated aiService.ts to pass runtime to buildSystemMessage()

This preserves existing test behavior (workspace-specific instructions work)
while adding robustness for SSH workspaces where files may not exist yet.

Author: ammar-agent

docs/instruction-files.md

@@ -2,14 +2,15 @@
 
 ## Overview
 
-cmux layers instructions from two locations:
+cmux layers instructions from multiple locations:
 
 1. `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
-2. `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — project-specific context
+2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context (if exists)
+3. `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — project fallback
 
 Priority within each location: `AGENTS.md` → `AGENT.md` → `CLAUDE.md` (first match wins). If the base file is found, cmux also appends `AGENTS.local.md` from the same directory when present.
 
-**Note**: Instructions are read from the project root (where the main repository is located), not from individual workspace directories. This ensures consistent instructions across all workspaces for a project.
+**Fallback behavior**: If a workspace doesn't have its own AGENTS.md, the project root's AGENTS.md is used as a fallback. This is particularly useful for SSH workspaces where files may not be fully cloned yet.
 
 ## Mode Prompts
 
@@ -21,7 +22,7 @@ cmux reads mode context from sections inside your instruction files. Add a headi
 
 Rules:
 
-- Project instructions are checked first, then global instructions
+- Workspace instructions are checked first, then project, then global instructions
 - The first matching section wins (at most one section is used)
 - The section's content is everything until the next heading of the same or higher level
 - Missing sections are ignored (no error)

src/services/aiService.ts

@@ -508,6 +508,7 @@ export class AIService extends EventEmitter {
       // Build system message from workspace metadata
       const systemMessage = await buildSystemMessage(
         metadata,
+        runtime,
         workspacePath,
         mode,
         additionalSystemInstructions

src/services/systemMessage.test.ts

@@ -5,13 +5,15 @@ import { buildSystemMessage } from "./systemMessage";
 import type { WorkspaceMetadata } from "@/types/workspace";
 import { spyOn, describe, test, expect, beforeEach, afterEach } from "bun:test";
 import type { Mock } from "bun:test";
+import { LocalRuntime } from "@/runtime/LocalRuntime";
 
 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
@@ -26,6 +28,9 @@ describe("buildSystemMessage", () => {
     // 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 () => {
@@ -55,7 +60,7 @@ Use diagrams where appropriate.
       projectPath: projectDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include the mode-specific content
     expect(systemMessage).toContain("<plan>");
@@ -86,7 +91,7 @@ Focus on planning and design.
       projectPath: projectDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir);
 
     // Should NOT include the <plan> mode-specific tag
     expect(systemMessage).not.toContain("<plan>");
@@ -125,7 +130,7 @@ Project plan instructions (should win).
       projectPath: projectDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include project mode section in the <plan> tag (project wins)
     expect(systemMessage).toMatch(/<plan>\s*Project plan instructions \(should win\)\./s);
@@ -160,7 +165,7 @@ Just general project stuff.
       projectPath: projectDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include global mode section as fallback
     expect(systemMessage).toContain("Global plan instructions");
@@ -181,7 +186,7 @@ Special mode instructions.
       projectPath: projectDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "My-Special_Mode!");
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "My-Special_Mode!");
 
     // Tag should be sanitized to only contain valid characters
     expect(systemMessage).toContain("<my-special_mode->");

src/services/systemMessage.ts

@@ -1,8 +1,10 @@
 import * as os from "os";
 import * as path from "path";
 import type { WorkspaceMetadata } from "@/types/workspace";
-import { gatherInstructionSets, readInstructionSet } from "@/utils/main/instructionFiles";
+import { gatherInstructionSets, readInstructionSet, readFileWithLocalVariant } from "@/utils/main/instructionFiles";
 import { extractModeSection } from "@/utils/main/markdown";
+import type { Runtime } from "@/runtime/Runtime";
+import { readFileString } from "@/utils/runtime/helpers";
 
 // NOTE: keep this in sync with the docs/models.md file
 
@@ -50,15 +52,58 @@ function getSystemDirectory(): string {
   return path.join(os.homedir(), ".cmux");
 }
 
+/**
+ * Read instruction set from a workspace using the runtime abstraction.
+ * This supports both local workspaces and remote SSH workspaces.
+ * 
+ * @param runtime - Runtime instance (may be local or SSH)
+ * @param workspacePath - Path to workspace directory
+ * @returns Combined instruction content, or null if no base file exists
+ */
+async function readInstructionSetFromRuntime(
+  runtime: Runtime,
+  workspacePath: string
+): Promise<string | null> {
+  const { INSTRUCTION_FILE_NAMES } = await import("@/utils/main/instructionFiles");
+  const LOCAL_INSTRUCTION_FILENAME = "AGENTS.local.md";
+
+  // Try to read base instruction file
+  let baseContent: string | null = null;
+  for (const filename of INSTRUCTION_FILE_NAMES) {
+    try {
+      const filePath = path.join(workspacePath, filename);
+      baseContent = await readFileString(runtime, filePath);
+      break; // Found one, stop searching
+    } catch {
+      // File doesn't exist or can't be read, try next
+      continue;
+    }
+  }
+
+  if (!baseContent) {
+    return null;
+  }
+
+  // Try to read local variant
+  try {
+    const localFilePath = path.join(workspacePath, LOCAL_INSTRUCTION_FILENAME);
+    const localContent = await readFileString(runtime, localFilePath);
+    return `${baseContent}\n\n${localContent}`;
+  } catch {
+    return baseContent;
+  }
+}
+
 /**
  * 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. Project instructions: <projectPath>/AGENTS.md (+ AGENTS.local.md)
- * 3. Mode-specific context (if mode provided): Extract a section titled "Mode: <mode>"
+ * 2. Workspace instructions: <workspacePath>/AGENTS.md (+ AGENTS.local.md) - if exists
+ * 3. Project instructions: <projectPath>/AGENTS.md (+ AGENTS.local.md) - fallback if workspace doesn't have one
+ * 4. 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: project instructions first, then global instructions.
+ *    precedence order: workspace instructions first, then project, then global instructions.
  *
  * Each instruction file location is searched for in priority order:
  * - AGENTS.md
@@ -69,6 +114,7 @@ function getSystemDirectory(): string {
  * checked and appended when building the instruction set (useful for personal preferences not committed to git).
  *
  * @param metadata - Workspace metadata (contains projectPath for reading AGENTS.md)
+ * @param runtime - Runtime instance for reading workspace files (may be remote)
  * @param workspacePath - Absolute path to the workspace directory (for environment context)
  * @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
@@ -77,6 +123,7 @@ function getSystemDirectory(): string {
  */
 export async function buildSystemMessage(
   metadata: WorkspaceMetadata,
+  runtime: Runtime,
   workspacePath: string,
   mode?: string,
   additionalSystemInstructions?: string
@@ -92,20 +139,37 @@ export async function buildSystemMessage(
   const systemDir = getSystemDirectory();
   const projectDir = metadata.projectPath;
 
-  // Gather instruction sets from both global and project directories
-  // Global instructions apply first, then project-specific ones
-  // Note: We read from projectPath (the main repo) not workspacePath (the worktree)
-  const instructionDirectories = [systemDir, projectDir];
-  const instructionSegments = await gatherInstructionSets(instructionDirectories);
-  const customInstructions = instructionSegments.join("\n\n");
+  // Read workspace instructions using runtime (may be remote for SSH)
+  // Try to read AGENTS.md from workspace directory first
+  const workspaceInstructions = await readInstructionSetFromRuntime(runtime, workspacePath);
+
+  // Gather instruction sets from global and project directories (always local)
+  // Note: We gather from both systemDir and projectDir, but workspace is handled separately
+  const localInstructionDirs = [systemDir, projectDir];
+  const localInstructionSegments = await gatherInstructionSets(localInstructionDirs);
+
+  // Combine all instruction sources
+  // Priority: global, workspace (if found), project (as fallback)
+  const allSegments = [...localInstructionSegments];
+  if (workspaceInstructions) {
+    // Insert workspace instructions after global (index 0) but before project
+    allSegments.splice(1, 0, workspaceInstructions);
+  }
+  const customInstructions = allSegments.join("\n\n");
 
-  // Look for a "Mode: <mode>" section inside instruction sets, preferring project over global
+  // Look for a "Mode: <mode>" section inside instruction sets
+  // Priority: workspace instructions, then project, then global
   // This behavior is documented in docs/instruction-files.md - keep both in sync when changing.
   let modeContent: string | null = null;
   if (mode) {
-    const projectInstructions = await readInstructionSet(projectDir);
-    if (projectInstructions) {
-      modeContent = extractModeSection(projectInstructions, mode);
+    if (workspaceInstructions) {
+      modeContent = extractModeSection(workspaceInstructions, mode);
+    }
+    if (!modeContent) {
+      const projectInstructions = await readInstructionSet(projectDir);
+      if (projectInstructions) {
+        modeContent = extractModeSection(projectInstructions, mode);
+      }
     }
     if (!modeContent) {
       const globalInstructions = await readInstructionSet(systemDir);

tests/ipcMain/sendMessage.test.ts

@@ -700,10 +700,11 @@ describeIntegration("IpcMain sendMessage integration tests", () => {
       "should include mode-specific instructions in system message",
       async () => {
         // Setup test environment
-        const { env, workspaceId, workspacePath, cleanup } = await setupWorkspace(provider);
+        const { env, workspaceId, tempGitRepo, cleanup } = await setupWorkspace(provider);
         try {
           // Write AGENTS.md with mode-specific sections containing distinctive markers
-          const agentsMdPath = path.join(workspacePath, "AGENTS.md");
+          // Note: AGENTS.md is read from project root, not workspace directory
+          const agentsMdPath = path.join(tempGitRepo, "AGENTS.md");
           const agentsMdContent = `# Instructions
 
 ## General Instructions