docs: def attached(self, worker, commands):
          """This is invoked by the Worker when the self.workername bot
          registers their builder.
  
          @type  worker: L{buildbot.worker.Worker}
          @param worker: the Worker that represents the worker as a whole
          @type  commands: dict: string -> string, or None
          @param commands: provides the worker's version of each RemoteCommand
  
          @rtype:  L{twisted.internet.defer.Deferred}
          @return: a Deferred that fires (with 'self') when the worker-side
                   builder is fully attached and ready to accept commands.
          """
          for w in self.attaching_workers + self.workers:
              if w.worker == worker:
                  # already attached to them. This is fairly common, since
                  # attached() gets called each time we receive the builder
                  # list from the worker, and we ask for it each time we add or
                  # remove a builder. So if the worker is hosting builders
                  # A,B,C, and the config file changes A, we'll remove A and
                  # re-add it, triggering two builder-list requests, getting
                  # two redundant calls to attached() for B, and another two
                  # for C.
                  #
                  # Therefore, when we see that we're already attached, we can
                  # just ignore it.
                  return defer.succeed(self)
  
          wfb = workerforbuilder.WorkerForBuilder()
          wfb.setBuilder(self)
          self.attaching_workers.append(wfb)
  
          try:
              wfb = yield wfb.attached(worker, commands)
              self.attaching_workers.remove(wfb)
              self.workers.append(wfb)
              return self
  
          except Exception as e:  # pragma: no cover
              # already log.err'ed by WorkerForBuilder._attachFailure
              # TODO: remove from self.workers (except that detached() should get
              #       run first, right?)
              log.err(e, 'worker failed to attach')
              return None