fix(core): remove spurious async from synchronous methods

29 require-await warnings and 1 unused eslint-disable directive.
All methods either implement an interface returning Promise<T> with a
synchronous body (return Promise.resolve() explicitly) or are private
helpers that never needed async in the first place (return bare
CommsResult).

Files changed:
- bridges/pi: eslint-disable for SDK-mandated async handler
- discovery backends: Promise.resolve() for interface-compliant stubs
- federation: Promise.resolve() for synchronous disconnect
- mesh-store: Promise.resolve() for fire-and-forget connectToRemote
- store: remove async from throw-only FileStore stubs
- transports: Promise.resolve() for synchronous removeListener/shutdown
- tool: return bare CommsResult from synchronous query methods
- test helper: remove unused eslint-disable directive

Author: Mearman

src/bridges/pi/index.ts

@@ -178,6 +178,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand("comms-url", {
     description: "Show the Agent Comms web UI URL",
+    // eslint-disable-next-line @typescript-eslint/require-await -- SDK requires Promise<void> return
     handler: async (_args, ctx) => {
       if (!webHandle) {
         ctx.ui.notify("Web UI is not running.", "error");

src/core/discovery-mdns.ts

@@ -63,7 +63,7 @@ export class MdnsDiscoveryBackend implements DiscoveryBackend {
     return id;
   }
 
-  async stopAdvertising(id: string): Promise<void> {
+  stopAdvertising(id: string): Promise<void> {
     void id;
 
     if (this.beaconTimer !== undefined) {
@@ -79,10 +79,12 @@ export class MdnsDiscoveryBackend implements DiscoveryBackend {
       this.socket = undefined;
       this.isListening = false;
     }
+
+    return Promise.resolve();
   }
 
   /** Stop all beacon activity and close the socket. */
-  async stop(): Promise<void> {
+  stop(): Promise<void> {
     if (this.beaconTimer !== undefined) {
       clearInterval(this.beaconTimer);
       this.beaconTimer = undefined;
@@ -95,6 +97,8 @@ export class MdnsDiscoveryBackend implements DiscoveryBackend {
       this.socket = undefined;
       this.isListening = false;
     }
+
+    return Promise.resolve();
   }
 
   async discover(

src/core/discovery-tailscale.ts

@@ -58,19 +58,21 @@ export class TailscaleDiscoveryBackend implements DiscoveryBackend {
   readonly name = "tailscale";
 
   /** No-op — the coordinator already listens on the Tailscale IP. */
-  async startAdvertising(opts: AdvertiseOptions): Promise<string> {
-    return `tailscale-${String(opts.port)}`;
+  startAdvertising(opts: AdvertiseOptions): Promise<string> {
+    return Promise.resolve(`tailscale-${String(opts.port)}`);
   }
 
   /** No-op — nothing to stop. */
-  async stopAdvertising(id: string): Promise<void> {
+  stopAdvertising(id: string): Promise<void> {
     void id;
+    return Promise.resolve();
   }
 
   /** Stop discovery — no-op since Tailscale has no persistent state to clean up. */
-  async stop(): Promise<void> {
+  stop(): Promise<void> {
     // Tailscale discovery is stateless — each discover() call probes peers fresh.
     // No persistent connections or timers to tear down.
+    return Promise.resolve();
   }
 
   /**

src/core/discovery.ts

@@ -199,24 +199,24 @@ export class DiscoveryManager {
     }
   }
 
-  private async resumeAllAdvertisements(): Promise<void> {
+  private resumeAllAdvertisements(): Promise<void> {
     // Restart backends first (they may have been stopped in "dark" mode)
     // Note: backends reinitialise their sockets on next startAdvertising/discover call.
     for (const [id] of this.pausedAdvertisements) {
       this.pausedAdvertisements.delete(id);
       // We can't fully resume without original opts — the caller must
       // re-advertise. Mark as not paused so new advertise calls work.
     }
+    return Promise.resolve();
   }
 
-  private async resumeAdvertisementsForBackend(
-    backendName: string,
-  ): Promise<void> {
+  private resumeAdvertisementsForBackend(backendName: string): Promise<void> {
     for (const [id, entry] of this.pausedAdvertisements) {
       if (entry.backendName === backendName) {
         this.pausedAdvertisements.delete(id);
       }
     }
+    return Promise.resolve();
   }
 
   /** Stop a previously started advertisement. */

src/core/federation.ts

@@ -171,15 +171,17 @@ export class FederationManager {
   // -----------------------------------------------------------------------
 
   /** Disconnect a specific federation link. */
-  async disconnect(linkId: string): Promise<void> {
+  disconnect(linkId: string): Promise<void> {
     const link = this.links.get(linkId);
-    if (!link) return;
+    if (!link) return Promise.resolve();
 
     this.clearLinkTimers(linkId);
     link.ready = false;
     link.socket.unref();
     link.socket.destroy();
     this.links.delete(linkId);
+
+    return Promise.resolve();
   }
 
   /** List all active federation links. */

src/core/mesh-store.ts

@@ -396,7 +396,7 @@ export class MeshStore implements CommsStore {
   /** Initiate an outbound connection to a remote coordinator requiring approval.
    *  Fires the connect_request and returns immediately. The connection
    *  completes asynchronously when the coordinator accepts or rejects. */
-  async connectToRemote(host: string, port: number): Promise<void> {
+  connectToRemote(host: string, port: number): Promise<void> {
     const agent = this.agents.get(this.peerId);
     // Fire-and-forget: don't await the full approval handshake.
     // The coordinator will either accept (triggering normal introduction flow)
@@ -415,6 +415,8 @@ export class MeshStore implements CommsStore {
         // Log silently — the calling tool already returned success.
         void err;
       });
+
+    return Promise.resolve();
   }
 
   /** Start only the data server without connecting to a coordinator.

src/core/store.ts

@@ -618,14 +618,14 @@ export class FileStore implements CommsStore {
   // Listener management — not supported by FileStore
   // -----------------------------------------------------------------------
 
-  async addListener(): Promise<string> {
+  addListener(): Promise<string> {
     throw new CommsError(
       "FileStore does not support listener management",
       "NOT_SUPPORTED",
     );
   }
 
-  async removeListener(): Promise<void> {
+  removeListener(): Promise<void> {
     throw new CommsError(
       "FileStore does not support listener management",
       "NOT_SUPPORTED",
@@ -644,14 +644,14 @@ export class FileStore implements CommsStore {
   // Federation — not supported by FileStore
   // -----------------------------------------------------------------------
 
-  async fedConnect(): Promise<string> {
+  fedConnect(): Promise<string> {
     throw new CommsError(
       "FileStore does not support federation",
       "NOT_SUPPORTED",
     );
   }
 
-  async fedDisconnect(): Promise<void> {
+  fedDisconnect(): Promise<void> {
     throw new CommsError(
       "FileStore does not support federation",
       "NOT_SUPPORTED",
@@ -664,14 +664,14 @@ export class FileStore implements CommsStore {
   // Connection approval — not supported by FileStore
   // -----------------------------------------------------------------------
 
-  async acceptConnection(): Promise<void> {
+  acceptConnection(): Promise<void> {
     throw new CommsError(
       "FileStore does not support connection approval",
       "NOT_SUPPORTED",
     );
   }
 
-  async rejectConnection(): Promise<void> {
+  rejectConnection(): Promise<void> {
     throw new CommsError(
       "FileStore does not support connection approval",
       "NOT_SUPPORTED",
@@ -688,14 +688,14 @@ export class FileStore implements CommsStore {
     return [];
   }
 
-  async connectToRemote(): Promise<void> {
+  connectToRemote(): Promise<void> {
     throw new CommsError(
       "FileStore does not support remote connections",
       "NOT_SUPPORTED",
     );
   }
 
-  async startDataServerOnly(): Promise<void> {
+  startDataServerOnly(): Promise<void> {
     throw new CommsError(
       "FileStore does not support network operations",
       "NOT_SUPPORTED",

src/core/tcp-transport.ts

@@ -344,7 +344,7 @@ export class TcpTransport implements MeshTransport {
     return id;
   }
 
-  async removeListener(id: string): Promise<void> {
+  removeListener(id: string): Promise<void> {
     const listener = this.coordinatorListeners.get(id);
     if (!listener) {
       throw new Error(`Listener ${id} not found`);
@@ -356,6 +356,8 @@ export class TcpTransport implements MeshTransport {
     listener.server.unref();
     listener.server.close();
     this.coordinatorListeners.delete(id);
+
+    return Promise.resolve();
   }
 
   listListeners(): ListenerInfo[] {
@@ -516,7 +518,7 @@ export class TcpTransport implements MeshTransport {
   // MeshTransport — Shutdown / unref
   // -----------------------------------------------------------------------
 
-  async shutdown(): Promise<void> {
+  shutdown(): Promise<void> {
     this.shutDown = true;
 
     // Destroy the coordinator client socket
@@ -569,6 +571,8 @@ export class TcpTransport implements MeshTransport {
     this.defaultListenerId = undefined;
 
     this._isCoordinator = false;
+
+    return Promise.resolve();
   }
 
   unref(): void {

src/core/tls-transport.ts

@@ -398,7 +398,7 @@ export class TlsTransport {
     return id;
   }
 
-  async removeListener(id: string): Promise<void> {
+  removeListener(id: string): Promise<void> {
     const listener = this.coordinatorListeners.get(id);
     if (!listener) {
       throw new Error(`Listener ${id} not found`);
@@ -410,6 +410,8 @@ export class TlsTransport {
     listener.server.unref();
     listener.server.close();
     this.coordinatorListeners.delete(id);
+
+    return Promise.resolve();
   }
 
   listListeners(): ListenerInfo[] {
@@ -569,7 +571,7 @@ export class TlsTransport {
   // MeshTransport — Shutdown / unref
   // -----------------------------------------------------------------------
 
-  async shutdown(): Promise<void> {
+  shutdown(): Promise<void> {
     this.shutDown = true;
 
     // Destroy the coordinator client socket
@@ -622,6 +624,8 @@ export class TlsTransport {
     this.defaultListenerId = undefined;
 
     this._isCoordinator = false;
+
+    return Promise.resolve();
   }
 
   unref(): void {

src/core/tool.ts

@@ -83,31 +83,31 @@ export class CommsTool {
         case "mesh_reject":
           return await this.meshReject(ctx, action);
         case "mesh_pending":
-          return await this.meshPending(ctx);
+          return this.meshPending(ctx);
         case "mesh_discover":
           return await this.meshDiscover(action);
         case "mesh_advertise":
           return await this.meshAdvertise(ctx, action);
         case "mesh_unadvertise":
           return await this.meshUnadvertise(action);
         case "mesh_interfaces":
-          return await this.meshInterfaces();
+          return this.meshInterfaces();
         case "mesh_listen":
           return await this.meshListen(ctx, action);
         case "mesh_unlisten":
           return await this.meshUnlisten(ctx, action);
         case "mesh_listeners":
-          return await this.meshListeners(ctx);
+          return this.meshListeners(ctx);
         case "mesh_set_visibility":
           return await this.meshSetVisibility(action);
         case "mesh_get_visibility":
-          return await this.meshGetVisibility(action);
+          return this.meshGetVisibility(action);
         case "mesh_fed_connect":
           return await this.meshFedConnect(ctx, action);
         case "mesh_fed_disconnect":
           return await this.meshFedDisconnect(ctx, action);
         case "mesh_fed_links":
-          return await this.meshFedLinks(ctx);
+          return this.meshFedLinks(ctx);
         default:
           return {
             content: `Unknown action: ${JSON.stringify(action).slice(0, 100)}`,
@@ -391,7 +391,7 @@ export class CommsTool {
     };
   }
 
-  private async meshInterfaces(): Promise<CommsResult> {
+  private meshInterfaces(): CommsResult {
     const interfaces = this.store.getNetworkInterfaces();
     if (interfaces.length === 0)
       return { content: "No network interfaces found.", isError: false };
@@ -464,7 +464,7 @@ export class CommsTool {
     }
   }
 
-  private async meshListeners(_ctx: CommsContext): Promise<CommsResult> {
+  private meshListeners(_ctx: CommsContext): CommsResult {
     const listeners = this.store.listListeners();
     if (listeners.length === 0)
       return { content: "No listeners (not coordinator).", isError: false };
@@ -496,9 +496,9 @@ export class CommsTool {
     };
   }
 
-  private async meshGetVisibility(
+  private meshGetVisibility(
     _action: CommsAction & { action: "mesh_get_visibility" },
-  ): Promise<CommsResult> {
+  ): CommsResult {
     if (!this.store.getVisibility) {
       return {
         content: "Visibility control is not available on this store.",
@@ -588,7 +588,7 @@ export class CommsTool {
     }
   }
 
-  private async meshFedLinks(_ctx: CommsContext): Promise<CommsResult> {
+  private meshFedLinks(_ctx: CommsContext): CommsResult {
     const links = this.store.fedLinks();
     if (links.length === 0)
       return { content: "No federation links.", isError: false };
@@ -621,7 +621,7 @@ export class CommsTool {
     }
   }
 
-  private async meshPending(_ctx: CommsContext): Promise<CommsResult> {
+  private meshPending(_ctx: CommsContext): CommsResult {
     const pending = this.store.listPendingConnections();
     if (pending.length === 0)
       return { content: "No pending connections.", isError: false };