🤖 fix: keep agent inheritance scoped in SSH workspaces

Anchor agent frontmatter/body resolution to the known definition scope so host-global
agents in SSH workspaces don't widen back into unnecessary project-scope SSH probes.
This preserves host-global agent discovery while avoiding the SSH stat hangs we
reproduced in integration tests.

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `xhigh` • Cost: `$60.79`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=xhigh costs=60.79 -->

Author: ethanndickson

src/node/orpc/router.ts

@@ -63,6 +63,7 @@ import {
 } from "@/node/services/agentSkills/agentSkillsService";
 import {
   discoverAgentDefinitions,
+  getSkipScopesAboveForKnownScope,
   readAgentDefinition,
   resolveAgentFrontmatter,
 } from "@/node/services/agentDefinitions/agentDefinitionsService";
@@ -1175,7 +1176,10 @@ export const router = (authToken?: string) => {
                 const resolvedFrontmatter = await resolveAgentFrontmatter(
                   runtime,
                   discoveryPath,
-                  descriptor.id
+                  descriptor.id,
+                  {
+                    skipScopesAbove: getSkipScopesAboveForKnownScope(descriptor.scope),
+                  }
                 );
 
                 const effectivelyDisabled = isAgentEffectivelyDisabled({

src/node/services/agentDefinitions/agentDefinitionsService.test.ts

@@ -9,6 +9,7 @@ import { RemoteRuntime, type SpawnResult } from "@/node/runtime/RemoteRuntime";
 import { DisposableTempDir } from "@/node/services/tempDir";
 import {
   discoverAgentDefinitions,
+  getSkipScopesAboveForKnownScope,
   readAgentDefinition,
   resolveAgentBody,
   resolveAgentFrontmatter,
@@ -163,6 +164,18 @@ class RemotePathMappedRuntime extends RemoteRuntime {
   }
 }
 
+class TrackingRemotePathMappedRuntime extends RemotePathMappedRuntime {
+  readonly statCalls: string[] = [];
+
+  override stat(
+    filePath: string,
+    abortSignal?: AbortSignal
+  ): ReturnType<RemotePathMappedRuntime["stat"]> {
+    this.statCalls.push(filePath);
+    return super.stat(filePath, abortSignal);
+  }
+}
+
 describe("agentDefinitionsService", () => {
   test("project agents override global agents", async () => {
     using project = new DisposableTempDir("agent-defs-project");
@@ -279,6 +292,44 @@ describe("agentDefinitionsService", () => {
     expect(body).toContain("Project instructions.");
   });
 
+  test("known global-scope resolution skips remote project probes during inheritance", async () => {
+    using project = new DisposableTempDir("agent-defs-ssh-frontmatter-project");
+    using global = new DisposableTempDir("agent-defs-ssh-frontmatter-global");
+
+    const remoteWorkspacePath = "/remote/workspace";
+    const projectAgentsRoot = path.join(project.path, ".mux", "agents");
+    const globalAgentsRoot = path.join(global.path, "agents");
+    await fs.mkdir(projectAgentsRoot, { recursive: true });
+    await fs.mkdir(globalAgentsRoot, { recursive: true });
+
+    await fs.writeFile(
+      path.join(globalAgentsRoot, "asklike.md"),
+      `---\nname: Ask Like\nbase: exec\n---\nAsk-like body.\n`,
+      "utf-8"
+    );
+
+    const roots = {
+      projectRoot: path.posix.join(remoteWorkspacePath, ".mux", "agents"),
+      globalRoot: globalAgentsRoot,
+    };
+    const runtime = new TrackingRemotePathMappedRuntime(project.path, remoteWorkspacePath);
+
+    const descriptors = await discoverAgentDefinitions(runtime, remoteWorkspacePath, { roots });
+    const askLike = descriptors.find((descriptor) => descriptor.id === "asklike");
+    expect(askLike).toBeDefined();
+    expect(askLike?.scope).toBe("global");
+
+    const frontmatter = await resolveAgentFrontmatter(runtime, remoteWorkspacePath, "asklike", {
+      roots,
+      skipScopesAbove: getSkipScopesAboveForKnownScope(askLike!.scope),
+    });
+
+    expect(frontmatter.name).toBe("Ask Like");
+    expect(runtime.statCalls.some((filePath) => filePath.endsWith("/.mux/agents/exec.md"))).toBe(
+      false
+    );
+  });
+
   test("resolveAgentBody appends by default (new default), replaces when prompt.append is false", async () => {
     using tempDir = new DisposableTempDir("agent-body-test");
     const agentsRoot = path.join(tempDir.path, ".mux", "agents");

src/node/services/agentDefinitions/agentDefinitionsService.ts

@@ -39,17 +39,44 @@ export function agentVisitKey(id: AgentId, scope: AgentDefinitionScope): string
   return `${id}:${scope}`;
 }
 
+/**
+ * When the caller already knows which scope supplied an agent definition, skip any higher-priority
+ * scopes so resolution stays anchored to that package instead of re-probing more specific roots.
+ *
+ * Examples:
+ * - Known global agent → skip project scope
+ * - Known built-in agent → skip project + global scopes
+ */
+export function getSkipScopesAboveForKnownScope(
+  scope: AgentDefinitionScope
+): AgentDefinitionScope | undefined {
+  switch (scope) {
+    case "project":
+      return undefined;
+    case "global":
+      return "project";
+    case "built-in":
+      return "global";
+  }
+}
+
 /**
  * Compute the skipScopesAbove value when resolving a base agent.
- * If the base has the same ID as the current agent, skip the current scope
- * to allow project/global agents to extend built-ins of the same name.
+ *
+ * Same-name inheritance (for example project/exec -> global|built-in exec) still skips the current
+ * scope entirely. Otherwise, keep the lookup anchored to the current package's scope so a known
+ * global or built-in agent does not widen back into project/global overrides during inheritance.
  */
 export function computeBaseSkipScope(
   baseId: AgentId,
   currentId: AgentId,
   currentScope: AgentDefinitionScope
 ): AgentDefinitionScope | undefined {
-  return baseId === currentId ? currentScope : undefined;
+  if (baseId === currentId) {
+    return currentScope;
+  }
+
+  return getSkipScopesAboveForKnownScope(currentScope);
 }
 
 const GLOBAL_AGENTS_ROOT = "~/.mux/agents";

src/node/services/agentResolution.ts

@@ -25,6 +25,7 @@ import { getErrorMessage } from "@/common/utils/errors";
 import { type ToolPolicy } from "@/common/utils/tools/toolPolicy";
 import type { Runtime } from "@/node/runtime/Runtime";
 import {
+  getSkipScopesAboveForKnownScope,
   readAgentDefinition,
   resolveAgentFrontmatter,
 } from "@/node/services/agentDefinitions/agentDefinitionsService";
@@ -147,7 +148,10 @@ export async function resolveAgentForStream(
       const resolvedFrontmatter = await resolveAgentFrontmatter(
         runtime,
         agentDiscoveryPath,
-        agentDefinition.id
+        agentDefinition.id,
+        {
+          skipScopesAbove: getSkipScopesAboveForKnownScope(agentDefinition.scope),
+        }
       );
 
       const effectivelyDisabled = isAgentEffectivelyDisabled({

src/node/services/streamContextBuilder.test.ts

@@ -87,7 +87,7 @@ async function buildSystemContextForTest(args: {
     metadata: args.metadata,
     workspacePath: args.workspacePath,
     workspaceId: args.metadata.id,
-    agentDefinition: { id: "exec" },
+    agentDefinition: { id: "exec", scope: "built-in" },
     agentDiscoveryPath: args.workspacePath,
     isSubagentWorkspace: args.isSubagentWorkspace,
     effectiveAdditionalInstructions: args.effectiveAdditionalInstructions,

src/node/services/streamContextBuilder.ts

@@ -20,6 +20,7 @@ import type { MuxMessage } from "@/common/types/message";
 import type { DesktopCapability } from "@/common/types/desktop";
 import type { ProjectsConfig } from "@/common/types/project";
 import type { MuxToolScope } from "@/common/types/toolScope";
+import type { AgentDefinitionScope } from "@/common/types/agentDefinition";
 import type { WorkspaceMetadata } from "@/common/types/workspace";
 import type { ProvidersConfigMap } from "@/common/orpc/types";
 import type { TaskSettings } from "@/common/types/tasks";
@@ -34,6 +35,7 @@ import {
   resolveAgentBody,
   resolveAgentFrontmatter,
   discoverAgentDefinitions,
+  getSkipScopesAboveForKnownScope,
   type AgentDefinitionsRoots,
 } from "@/node/services/agentDefinitions/agentDefinitionsService";
 import { isAgentEffectivelyDisabled } from "@/node/services/agentDefinitions/agentEnablement";
@@ -222,7 +224,7 @@ export interface BuildStreamSystemContextOptions {
   workspacePath: string;
   workspaceId: string;
   /** Agent definition (may have fallen back to exec). Use `.id` for resolution. */
-  agentDefinition: { id: string };
+  agentDefinition: { id: string; scope: AgentDefinitionScope };
   agentDiscoveryPath: string;
   isSubagentWorkspace: boolean;
   effectiveAdditionalInstructions: string | undefined;
@@ -453,15 +455,20 @@ export async function buildStreamSystemContext(
 
   // Resolve the body with inheritance (prompt.append merges with base).
   // Use agentDefinition.id (may have fallen back to exec) instead of effectiveAgentId.
-  const resolvedBody = await resolveAgentBody(runtime, agentDiscoveryPath, agentDefinition.id);
+  const resolvedBody = await resolveAgentBody(runtime, agentDiscoveryPath, agentDefinition.id, {
+    skipScopesAbove: getSkipScopesAboveForKnownScope(agentDefinition.scope),
+  });
 
   let subagentAppendPrompt: string | undefined;
   if (isSubagentWorkspace) {
     try {
       const resolvedFrontmatter = await resolveAgentFrontmatter(
         runtime,
         agentDiscoveryPath,
-        agentDefinition.id
+        agentDefinition.id,
+        {
+          skipScopesAbove: getSkipScopesAboveForKnownScope(agentDefinition.scope),
+        }
       );
       subagentAppendPrompt = resolvedFrontmatter.subagent?.append_prompt;
     } catch (error: unknown) {
@@ -605,7 +612,10 @@ export async function discoverAvailableSubagentsForToolContext(args: {
           args.runtime,
           args.workspacePath,
           descriptor.id,
-          { roots: args.roots }
+          {
+            roots: args.roots,
+            skipScopesAbove: getSkipScopesAboveForKnownScope(descriptor.scope),
+          }
         );
 
         const effectivelyDisabled = isAgentEffectivelyDisabled({

src/node/services/taskService.ts

@@ -13,6 +13,7 @@ import type { InitStateManager } from "@/node/services/initStateManager";
 import { log } from "@/node/services/log";
 import {
   discoverAgentDefinitions,
+  getSkipScopesAboveForKnownScope,
   readAgentDefinition,
   resolveAgentFrontmatter,
 } from "@/node/services/agentDefinitions/agentDefinitionsService";
@@ -1195,7 +1196,10 @@ export class TaskService {
                 const frontmatter = await resolveAgentFrontmatter(
                   runtime,
                   parentWorkspacePath,
-                  agent.id
+                  agent.id,
+                  {
+                    skipScopesAbove: getSkipScopesAboveForKnownScope(agent.scope),
+                  }
                 );
                 if (frontmatter.subagent?.runnable !== true) {
                   return null;